1

I'm considering a few different possible flows for a restful api. For minimum viable product, I'm assuming a web browser as the front end.

Current use case: the task of the human operator is to create an ordered collection of entities. Each entity will have some values assigned by the user. The assumption is that the user will be creating entries in ascending order, but that some back tracking will be required to correct data errors.

Insertion, removal, re-ordering and normalization will be supported by different interfaces. For values that can be predicted with high confidence, the initial presentation of the data entry resources should assume that those values are immutable, but provide links to resources that offer the human operator greater control. Dynamic operator assistance (think typeahead) is out of scope for mVP.

Manual manipulation of the URLs is not supported. The host is expected to classify externally generated URLs as hostile (but not for mVP, of course).

Question #1: is there any prior are describing the best practices for building such a thing? It would be nice to review, for instance, a list of use cases I haven't considered yet before I get deeply invested in the wrong design.

As I'm going to be using a browser as the front end, all of the requests that I dispatch are going to be using GET or POST.

As the entries, and the list itself, are entities, they will each have a uuid assigned to them. This would be one of the high confidence values that I expect to excuse the human operator from entering.

To first order, the operator's next task is always going to be entering data in a form. So the design should get the designer to the most likely next form as simply as possible.

The home page is published as the entry point to the api. As uses cases for reads are more common than use cases for writes, the operator will need to follow a GET relation to access the data entry states.

My initial implementation coupled the resources very tightly to the entities.

  • Follow (GET) a link to the form that creates the collection entity
  • User POSTs data to the endpoint
  • Server generates id for the new collection
  • Server creates the collection
  • Server redirects the user to a representation of the created collection

In this design, the form itself persists at the given location, which limits how much transient data I can include.

It occurred to me this evening that I don't need to lock myself in quite so tightly. A slightly different ordering

  • Follow (GET) a link to the form that creates the collection entity
  • Server generates id for the new collection
  • Server redirects to a representation of the form with the new ids specified
  • User POSTs data to the endpoint
  • Server creates the collection
  • Server generates ids for the next anticipated step
  • Server redirects the user to a representation of the created collection, with a form supporting the next task, with pre-generated ids, ready to go.
  • turtles all the way down

Given that "extra" round trips that don't require action by the human operator are acceptable, are there reasons to avoid persuing the second design?

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.