Skip to content

Instantly share code, notes, and snippets.

@lukepuplett
Created December 4, 2018 13:50
Show Gist options
  • Save lukepuplett/0d7e9dfb38292b168c64636f3db36fd7 to your computer and use it in GitHub Desktop.
Save lukepuplett/0d7e9dfb38292b168c64636f3db36fd7 to your computer and use it in GitHub Desktop.
REST API journey for updating an address on an insurance quote
```
Insurance quote people microservice.
rel method href
GET /
{ // Root links }
people:quotes GET /quotes
{ // List of quotes each with links }
people:view-quote GET /quotes/123?quoteStatus=Accepted
{ // Single quote stub with links }
people:furtherdetails GET /quotes/123/people/client/furtherdetails
{ // More detail on the client with links }
people:change-address GET /quotes/123/people/client/furtherdetails/addresses/home/editor?postcode=se11se
{ // List of addresses in SE11SE each with links }
people:pick-address GET /quotes/123/people/client/furtherdetails/addresses/home/editor?postcode=se11se&pick=0
{ // Single address with link to save to quote }
people:set-as-new-address PUT { ... } /quotes/123/people/client/furtherdetails/addresses/home
{ // Echoes the updated home address with links }
return "home" ? Returning home requires quoteStatus
```
@lukepuplett
Copy link
Author

This illustrates just how much extra work is required for a microservice holding the people associated with an insurance quote using REST-over-HTTP as the style of API for the microservice as opposed to CRUD-over-HTTP or even SOAP or Remoting.

Every action and transition must be journeyed and built just like a traditional website. The only difference, in this API at least, is the use of JSON instead of HTML.

Designing and testing is as much work as for a website, each link and the rules around its appearance, driving and automating journeys is a lot of work.

Specifying (esp. using any of the common API spec formats) everything even a fairly small API can do doesn't scale, it becomes apparent that the spec is either only a gist for the developer else it cannot cover all the various states and representations, it would be like exhaustively specifying every web page for a traditional website.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment