DRAFT Define an API layer for VRMS

[fyliu]

DRAFT

• trying to come up with good examples to show how this is different from the "create table" issues

Overview

As a backend project, we need a well-defined API layer to act as the acceptance criteria for developers to know when to stop working on features. It should cover exactly what VRMS needs from the backend. This will require collaboration between PD and VRMS.

Action Items

• [ ] Decide who will work on defining the API. See Discussion below
• [ ] Make a list of API functionalities we need and the order they should be worked on. See draft below
• [ ] Create issues for the API functionalities

Resources/Instructions

This issue came about from a helpful discussion in another issue when I realized this is what we need. https://github.com/hackforla/peopledepot/issues/143#issuecomment-1501230473

Who can we get to work on defining the API (in order of preference):

1. Ideally, we would meet with a tech lead(s) from VRMS who has a good idea of their needs and work on the API collaboratively.
2. Otherwise, we would like to meet with the next best person(s) from VRMS that understands their workflow designs and maybe data access pattern needs.
3. The fallback is undesirable for us but we would make a guess at what VRMS needs and create the API ourselves. It's bad because we end up telling VRMS what data they need to want from us and how they need to access them. They might end up needing something else and then we will need to redo our work.

What APIs do we need:

We don't need these. VRMS would do these steps with cognito directly.

Sign in

1. Sign up (guest)
2. Log in (guest)
3. Log in (member)

We do need these, and this is not a complete list:

Projects

1. Create a new project (admin)
2. Set a project admin (admin)
3. View list of projects (admin / project admin?)
4. Edit project details (admin / project admin?)
5. Join a project or assign user to a project (member? / project admin?)

Events

1. Create an event (admin? / project admin?)
2. View upcoming events (member / guest?)
3. Check-in to an event (member)

There are situations that VRMS will be able to tell us, like:

1. The user clicks on a project from the projects list to bring up the project's details. So we need to be able to lookup a project's details by project id (data available in project details).
2. The user creates a new event from the project details page. So we need to be able to create a new event that is associated to a project. We can require the project association unless there's another situation for creating an event that's not associated with a project.
3. The admin creates a new project, goes in to view its details, and sets a project admin from there. Clicking the button brings up a list of users filtered by their looking for a project lead role and sorted by the date they joined. So we need to be able to get a list of users with the necessary filters and ordering. Clicking on a user brings up the user's details side by side with the project details , with matching user experiences and project needs highlighted (maybe CTJ functionality?). Clicking a button sets up the association. So we need to be able to set project admin using data available in project details and user details.

This last situation show that the frontend workflows can make use of API functionality for multiple tables. The users list API needs to have certain filters and sorts to support this use, where as the users list that an admin sees by default might not require them or might have different requirements.

Going through all the frontend user stories will give us a complete set of API requirements that we need to support for what FE needs from us. Ideally, someone from VRMS could make a first pass attempt at it before meeting with PD. Tech leads are better because they would understand that, to create an association, you'd need a user id and a project id, just to give an example. They would catch problems like that before it gets to us.

[fyliu]

I'm closing this. We're making good progress at refining the design of the backend and there's enough examples along the way. So we don't need an issue to do that. Also, it seems like we have more information about how the system is supposed to work than the frontend team, so we don't need to get them involved for this right now.