![Recommended Status Codes
• 200 OK – [GET]
• 201 CREATED – [POST/PUT/PATCH]
• 202 ACCEPTED – [POST], async action
• 204 NO CONTENT – [DELETE]
• 400 BAD REQUEST – [*]
• 404 NOT FOUND – [*]
• 500 INTERNAL SERVER ERROR – [*]](https://image.slidesharecdn.com/e31af035-c967-43ee-a1e8-63f4faaa6982-150804094909-lva1-app6891/85/RestfulDesignRules-8-320.jpg)
RestfulDesignRules
- 2. Why? – adds value • Encourages a Contract-First API service • Rules help design for scalable services • Establishes a design standard and language • Rules promotes a “crisp”API making happy clients, reducing Support costs and sells the API (Netflix, Google, Github) • Sources : Apache project, Roy Fielding thesis • “Rest API Design Rule Book” - Mark Masse (O'Reilly Pub)
- 3. Web Architecture Scalability Constraints • Client-Server: must play distinct roles • Uniform Interface: standard interaction between client and server components • Cache : reduce latency, improve availability. Client or server • Stateless: resource at server has no state. Only client has conversational state
- 4. Uniform Interface • Identify service resources with an address: URI • Resource representation – resource returns different representations to different clients • Self descriptive – desired resource state reflected in request and current state in response. An update is successful or not • Links(HATEOAS) – current state defines links to related allowed links, may depend on client
- 5. Questions • How do I design for self-descriptive messages? • REST models state – how do I model this? • What URI name shall I use for CRUD services? • What URI name shall I use for non-CRUD services? • What HTTP response status codes to use for use cases?
- 6. REST Modeling • HTTP methods for CRUD or non-CRUD services • Document/Resource – object, record : animal • Collection resource – many related objects: animals (=database) • Store resource – many unrelated documents • Controller resource – process resource • Idempotent – side affect free • URI path – hierarchy of resources; /cats/felix
- 7. HTTP Method-Service Map • GET(SELECT) – Retrieve document(s) • POST(CREATE) – Create a new resource in a collection • POST(PROCESS) – Perform non-CRUD process • PUT(UPDATE) – Update resource • DELETE(DELETE) – Delete resource • PATCH(UPDATE) – Update with changes • HEAD – Get metadata or “ping” resource • OPTIONS – Get resource’s “Allowed” URI links
- 8. Recommended Status Codes • 200 OK – [GET] • 201 CREATED – [POST/PUT/PATCH] • 202 ACCEPTED – [POST], async action • 204 NO CONTENT – [DELETE] • 400 BAD REQUEST – [*] • 404 NOT FOUND – [*] • 500 INTERNAL SERVER ERROR – [*]
- 9. Expected URI & Responses • GET /collection : Return list of resources • GET /collection/resourceId: Return a resource • POST /collection : Create resource, return Id • PUT /collection/resourceId : Update resource • DELETE /collection/resource : Return empty body • PATCH /collection/resource : Return updated resource
- 10. State REL links - HATEOAS { // fields … “links” : { “self” : { “href” : http://api.project.company.org/departments/1/employee/100 }, “parent” : { “href” : http://api.project.company.org/departments/1 }, “outOfOffice” : { // Out of office state change “href” : http://api.project.company.org/departments/1/employee/100/outOfOffice “method”:”POST” }, } }
- 11. HATEOAS • Hypermedia as the engine of state • Decouples client and server. No hard coded URIs in client • REST service controls state transitions through available links • Available Open Source libraries to generate links
- 12. Pagination • Use filter query parameters &page=1 • Normal GET resource must not use query parameters • Filter on start, end page and page size • Returned HATEOAS links must define href links with rel elements for = “next”, “previous”,”first” and “last”
- 13. REST Rules • Separator (/) indicates a hierarchy relationship • Trailing slash (/) must not be included in URIs • Singular noun for document names • Plural noun for collection and store names • Verb or verb phrase for controller names • Exclude file extensions in URIs (no .xml etc) • CRUD function names should not be used in URIs; not /deleteUser/1234 but /user/1234