RESTful API Desgin

Developing RESTful API

Transcript

1. P E D R A M N E G A H D A R RESTful API Design
2. Nouns > Verbs —  Verbs offer very little flexibility because they are tightly couples with a specific action. —  Instead use nouns with complementing HTTP action verbs (GET, POST, PUT….) —  Be judicious when creating custom verb/actions
3. Pick Resources Appropriately —  Resource granularity ¡  /items,/things (Too abstract) ¡  /document-with-coverimage, /jpegdocument (Too Specific) ¡  /document (Just Right) ÷  Conveys a sense of purpose and a sense of structure without being to specific to what it is. —  Don’t Tunnel Resources ¡  /services?operation=“customerAdd” ÷  Resource becomes service endpoint for everything “God Endpoints”
4. —  Recommendation ¡  Right granularity ¡  Avoid tunneling with resources ¡  Resource Names ÷  Pick meaningful names based on functionality ÷  Plural! /users,/dogs,/invoices
5. Simplify Relationships —  Avoid reflecting relationships in models ¡  Relationships in the model requires the client to add a lot of code to manage the meaning of this relationship. ¡  The relationship between user and reminder is not very clear just from the urls —  Recommendations ¡  Return models without associations where possible ¡  Reflect associations through URI nesting ÷  @GET @Path(“/user/{userid}/reminder{reminderid”}
6. Allow Choice of Formats —  JSON is the way to go. ¡  More compact/better for mobile ¡  Easy consumption from JavaScript —  Support both JSON and XML if time constraints are non-existent. ¡  East to implement XML & JSON in JAX-RS
7. Don’t Reveal stuff under the Hood —  Developers love APIs that hide the messy details —  Durable naming (Services and Resources) ¡  Avoid organization names ¡  Avoid project and code names ¡  Avoid acronyms —  Identifiers ¡  Avoid leaking internal identifiers to outside clients/systems —  Errors and Exceptions ¡  Errors can also leak out messy implementation details
8. —  Recommendations ¡  Name services and resources based on functionality ¡  Catch internal errors and then expose standard errors for your API ¡  Leverage HTTP standard error codes
9. Fast and Highly Available —  API response-time essential ¡  End-user experience ¡  Cost the developer money in lost transactions ¡  Impact brand and reputation —  Avoid ¡  Forcing clients to wait for long running transactions ¡  Forcing constant polling for changes to your data —  Recommendations ¡  Provide asynchronous messaging/tasks ¡  99.9+% of your APIs calls within 500 milliseconds
10. Standard —  Provide consistency throughout the API ¡  Leverage industry technologies/libraries —  Consistency ¡  Discovery/documentation ¡  Security protocols ¡  Service names/resources ¡  Errors/exceptions ¡  Onboarding experience