Outline REST API #115

rajadain · 2022-10-10T00:09:31Z

Overview

Adds an outline of the REST API so we have common target to hit.

Closes #116

Testing Instructions

Read through the document, ensure it makes sense

Checklist

fixup! commits have been squashed
CHANGELOG.md updated with summary of features or fixes, following Keep a Changelog guidelines
README.md updated if necessary to reflect the changes
CI passes after rebase

rajadain

Left some comments. Discussion encouraged.

rajadain · 2022-10-10T00:12:36Z

doc/arch/adr-002-rest-api.md

+| `/auth/login/`  | POST   | `{ ... }` | Allow Any      | 200 OK,<br />400 Bad Request,<br />401 Not Authorized | Used for starting new valid session          |
+| `/auth/logout/` | POST   | -         | Logged In User | 200 OK                                                | Used for logging out                         |
+
+### Boundaries


I'm a little conflicted about the Boundary / Submission separation. In our data model, the Boundary is the top-level entity, which may have one or more Submissions through its life. But in the UI, we're calling everything Submissions, so this is getting a little confusing.

I'm willing to get rid of Boundary and just treat Utilities as boundaries (== groups of submissions).

To flesh out that thought a little: otherwise, if we leave Boundary as a model, then I'm okay with the design in this ADR as is.

A utility can have multiple boundaries submitted over the years, and each boundary is a group of submissions, so we can't make that direct link. Need something in between.

I'm a bit confused by this.

With /boundaries/{id}/submit/, is the id the submission ID or the boundary ID? If not the submission ID, then where is that data? In the body of the request? I don't think we can determine the submission ID just from the boundary ID.

But in the UI, we're calling everything Submissions, so this is getting a little confusing.

The users aren't going to see the API routes, so why not use naming that reflects the data model?

A utility can have multiple boundaries submitted over the years, and each boundary is a group of submissions, so we can't make that direct link. Need something in between.

Right, but I'm not aware of any designs that pay attention to years, I thought all of that was going to be handled on the backend with get_latest submissions etc. Maybe we should consider adding a year field to Boundary to make it explicit? Could be discussed in a separate thread.

We make them transparent to the front-end because the correct one can be determined in the back-end?

Correct.

I'm imagining that POSTing to /boundaries/ creates a Boundary and a Submission, and returns details for both. POSTING to /boundaries/{id}/submit/ updates the Submission with notes and sets its submitted_at and submitted_by.

This reveals that we need an additional endpoint for creating a second draft submission. I'll add one.

But only one draft can be in review at a time? (Because 0-1 reviews per boundary.)

Correct, only one active submission (in draft or submitted state) at a time.

Update from scrum: not merely one draft in review at a time, but one draft at a time period. Coworkers will be collaborating on the same draft. I guess my question didn't make sense because a draft can't be in review.

rajadain · 2022-10-10T00:15:13Z

doc/arch/adr-002-rest-api.md

+| `/boundaries/`                             | GET    | -                        | Logged In User | 200 OK                                                     | Returns list of all boundaries the user has access to                                                              |
+| `/boundaries/?utilities=1,3,5,8`           | GET    | -                        | Logged In User | 200 OK,<br />401 Not Authorized                            | Returns list of boundaries in the given utilities. If the user does not have access to that utility, returns a 401 |
+| `/boundaries/`                             | POST   | `{ ... }`                | Contributor    | 201 Created,<br />400 Bad Request,<br />401 Not Authorized | Creates a new boundary if the payload is correct and the user is authorized                                        |
+| `/boundaries/{id}/`                        | GET    | -                        | Logged In User | 200 OK,<br />404 Not Found                                 | Returns boundary details if the users has access to it, else 404s. Includes all details about the boundary.        |


When GETing, this would include:

The shape

List of ~~reference layers~~ reference images

Current status (Draft / Submitted / etc)

Current Review Annotations

Activity Log

Created At, Created By, etc

List of reference layers

For my own understanding: this refers to reference images?

Good catch! Yes I mean reference images.

rajadain · 2022-10-10T00:17:25Z

doc/arch/adr-002-rest-api.md

+    boundary = get_object_or_404(Boundary, id)
+    submission = boundary.get_latest_submission_for(user)
+
+    serializer = SubmissionSerializer(submission)


This is also confusing, because the endpoint is called get_boundary but we're returning a serialized submission.

Perhaps there can be a BoundaryDetailSerializer that takes a boundary and does the get_latest_submission_for(user) within it, so we can return that here.

doc/arch/adr-002-rest-api.md

jacobtylerwalls · 2022-10-10T11:51:58Z

doc/arch/adr-002-rest-api.md

+
+| Path            | Method | Body      | Authentication | Responses                                             | Notes                                        |
+| --------------- | ------ | --------- | -------------- | ----------------------------------------------------- | -------------------------------------------- |
+| `/auth/login/`  | GET    | -         | Allow Any      | 200 OK,<br />401 Not Authorized                       | Returns loging JSON if current session valid |


I didn't think this request returned anything other than a status code.

This should return at least the Role of the user, so decisions can be made in the front-end. It may also return the user's email, which can be shown in the UI as the currently logged in user. We don't have a spot for this in the UI, but most apps do, and we may well have one at some point.

doc/arch/adr-002-rest-api.md

jacobtylerwalls · 2022-10-10T11:57:20Z

doc/arch/adr-002-rest-api.md

+| `/boundaries/`                             | GET    | -                        | Logged In User | 200 OK                                                     | Returns list of all boundaries the user has access to                                                              |
+| `/boundaries/?utilities=1,3,5,8`           | GET    | -                        | Logged In User | 200 OK,<br />401 Not Authorized                            | Returns list of boundaries in the given utilities. If the user does not have access to that utility, returns a 401 |
+| `/boundaries/`                             | POST   | `{ ... }`                | Contributor    | 201 Created,<br />400 Bad Request,<br />401 Not Authorized | Creates a new boundary if the payload is correct and the user is authorized                                        |
+| `/boundaries/{id}/`                        | GET    | -                        | Logged In User | 200 OK,<br />404 Not Found                                 | Returns boundary details if the users has access to it, else 404s. Includes all details about the boundary.        |


List of reference layers

For my own understanding: this refers to reference images?

doc/arch/adr-002-rest-api.md

Co-authored-by: Jacob Walls <jwalls@azavea.com>

doc/arch/adr-002-rest-api.md

rachelekm

I don't have any other comments that haven't already been discussed and clarified—thank you for writing this up!

skip-ci: true

rajadain · 2022-10-10T17:33:17Z

Thanks for all the reviews!

Eventually we'll have a Swagger API for this, but until then we should try to keep this ADR up to date whenever we add new endpoints.

rajadain force-pushed the tt/rest-api-design branch from 9cf7566 to 478bea2 Compare October 10, 2022 00:11

Outline REST API

a6b1a8a

rajadain force-pushed the tt/rest-api-design branch from 478bea2 to a6b1a8a Compare October 10, 2022 00:14

rajadain commented Oct 10, 2022

View reviewed changes

rajadain requested review from jacobtylerwalls, mstone121 and rachelekm October 10, 2022 00:18

rajadain added the Task 3.3 Django back-end label Oct 10, 2022

jacobtylerwalls reviewed Oct 10, 2022

View reviewed changes

jacobtylerwalls mentioned this pull request Oct 10, 2022

Drop Role table #117

Merged

4 tasks

rajadain and others added 3 commits October 10, 2022 08:49

Apply suggestions from code review

9567d21

Co-authored-by: Jacob Walls <jwalls@azavea.com>

Mention password reset endpoints

8507d2c

Better explain absence of review id for annotation updates

d4675f2

jacobtylerwalls approved these changes Oct 10, 2022

View reviewed changes

rajadain marked this pull request as ready for review October 10, 2022 13:22

Add endpoint to make new drafts

048a753

mstone121 approved these changes Oct 10, 2022

View reviewed changes

mstone121 mentioned this pull request Oct 10, 2022

Add boundary views and serializers #113

Merged

4 tasks

jacobtylerwalls reviewed Oct 10, 2022

View reviewed changes

doc/arch/adr-002-rest-api.md Outdated Show resolved Hide resolved

Add endpoint to update reference images

4e79c16

rachelekm approved these changes Oct 10, 2022

View reviewed changes

Update CHANGELOG

33e064e

skip-ci: true

rajadain merged commit 100e8d0 into develop Oct 10, 2022

rajadain deleted the tt/rest-api-design branch October 10, 2022 17:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Outline REST API #115

Outline REST API #115

rajadain commented Oct 10, 2022 •

edited

Loading

rajadain left a comment

rajadain Oct 10, 2022

jacobtylerwalls Oct 10, 2022

jacobtylerwalls Oct 10, 2022

rajadain Oct 10, 2022

mstone121 Oct 10, 2022

jacobtylerwalls Oct 10, 2022

rajadain Oct 10, 2022

jacobtylerwalls Oct 10, 2022

rajadain Oct 10, 2022

jacobtylerwalls Oct 10, 2022 •

edited

Loading

rajadain Oct 10, 2022 •

edited

Loading

jacobtylerwalls Oct 10, 2022

rajadain Oct 10, 2022

rajadain Oct 10, 2022

jacobtylerwalls Oct 10, 2022

rajadain Oct 10, 2022

jacobtylerwalls Oct 10, 2022

rachelekm left a comment

rajadain commented Oct 10, 2022

Outline REST API #115

Outline REST API #115

Conversation

rajadain commented Oct 10, 2022 • edited Loading

Overview

Testing Instructions

Checklist

rajadain left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jacobtylerwalls Oct 10, 2022 • edited Loading

Choose a reason for hiding this comment

rajadain Oct 10, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rachelekm left a comment

Choose a reason for hiding this comment

rajadain commented Oct 10, 2022

rajadain commented Oct 10, 2022 •

edited

Loading

jacobtylerwalls Oct 10, 2022 •

edited

Loading

rajadain Oct 10, 2022 •

edited

Loading