Download as PDF, PPTX
![miredotmiredotmiredot
REST Design Principles – Operations
Choose your operation wisely!
POST /dogs/5/toys
PUT /dogs/5/toys/2
GET /dogs/5
GET /dogs?fur=brown
DELETE /dogs/5/toys/2
Give dog 5 a new toy
Change something about his toy
Get all data of dog 5
Get all dogs called Snoopy
Take away his toy
200 OK
[{ “name”: “Scooby Doo” },
{ “name”: “Lassie” }]
N/A
request response](https://image.slidesharecdn.com/restdesignanddocumentation-slideshareedit-160729113453/85/RESTFul-API-Design-and-Documentation-an-Introduction-11-320.jpg)
Uploaded byMiredot
RESTFul API Design and Documentation - an Introduction
The document provides an introduction to RESTful API design and documentation, discussing the principles and practices necessary for creating effective APIs. Key points include the importance of predictable behavior, consistent URI structures, and proper HTTP methods for operations. It also emphasizes the necessity of thorough documentation for both private and public APIs to ensure usability and developer satisfaction.
More Related Content
Similar to RESTFul API Design and Documentation - an Introduction
![Lect 1 Number systems and base conversions. [Autosaved].pptx](https://cdn.slidesharecdn.com/ss_thumbnails/lect1numbersystemsandbaseconversions-260111134109-67c2d865-thumbnail.jpg?width=640&height=640&fit=bounds)
RESTFul API Design and Documentation - an Introduction
- 1. miredotmiredot miredot RESTful API Designand Documentation – an Introduction BeJUG April 2016
- 2. miredotmiredotmiredot Agenda REST – Whatand Why? Basic REST Design Principles Documenting a REST API Quick Demos Miredot POST https://api.twitter.com/tweets { “status”: “Great to be at BeJUG" } POST https://api.twitter.com/1.1/statuses/update.json?status=Great%20to%20be%at%BeJUG * **
- 3. miredotmiredotmiredot REST – Whatand Why? REpresentational State Transfer Things/resources instead actions (SOAP/RPC) Using HTTP the right way Stateless (if possible) Cache-able, Firewall-able, Proxy-able (JSON) For purists: know the initial URI and navigate via hyperlinks (HATEAOS)
- 4.
- 5. miredotmiredotmiredot REST Design Principles ReligiouslyRESTful vs REST-like Goals 1. Easy to use API 2. Predictable behavior 3. Works with existing infrastructure (proxies, browsers) Don’t think Java, think API first!
- 6. miredotmiredotmiredot REST Design Principles– URI / Resource https://api.acme.com/petstore/dogs/5/toys/2/parts base URL all the dogs dog with id=5 toy with id=2 all the toys of dog 5 all the parts of toy 2 ?material=plastic Rule1: Plural for collections, ID for single element Rule2: No verbs! ../petstore/dogs/add Rule3: Query params only for meta-info (filtering, format) extra info
- 7. miredotmiredotmiredot REST Design Principles– Operations Choose your operation wisely! POST /dogs/5/toys PUT /dogs/5/toys/2 GET /dogs/5 GET /dogs?fur=brown DELETE /dogs/5/toys/2 Give dog 5 a new toy Change something about his toy Get all data of dog 5 Get all dogs called Snoopy Take away his toy POST = Create PUT = Update (or create) GET = Read DELETE = Delete
- 8. miredotmiredotmiredot REST Design Principles– Operations Choose your operation wisely! POST /dogs/5/toys PUT /dogs/5/toys/2 GET /dogs/5 GET /dogs?fur=brown DELETE /dogs/5/toys/2 Give dog 5 a new toy Change something about his toy Get all data of dog 5 Get all dogs called Snoopy Take away his toy 201 CREATED “2” { “name”: “chicken” } request response
- 9. miredotmiredotmiredot REST Design Principles– Operations Choose your operation wisely! POST /dogs/5/toys PUT /dogs/5/toys/2 GET /dogs/5 GET /dogs?fur=brown DELETE /dogs/5/toys/2 Give dog 5 a new toy Change something about his toy Get all data of dog 5 Get all dogs called Snoopy Take away his toy 200 OK{ “name”: “duck” } request response
- 10. miredotmiredotmiredot REST Design Principles– Operations Choose your operation wisely! POST /dogs/5/toys PUT /dogs/5/toys/2 GET /dogs/5 GET /dogs?fur=brown DELETE /dogs/5/toys/2 Give dog 5 a new toy Change something about his toy Get all data of dog 5 Get all dogs called Snoopy Take away his toy 200 OK { “name”: “Snoopy” “favouriteToy”: 2 } N/A request response
- 11. miredotmiredotmiredot REST Design Principles– Operations Choose your operation wisely! POST /dogs/5/toys PUT /dogs/5/toys/2 GET /dogs/5 GET /dogs?fur=brown DELETE /dogs/5/toys/2 Give dog 5 a new toy Change something about his toy Get all data of dog 5 Get all dogs called Snoopy Take away his toy 200 OK [{ “name”: “Scooby Doo” }, { “name”: “Lassie” }] N/A request response
- 12. miredotmiredotmiredot REST Design Principles– Operations Choose your operation wisely! POST /dogs/5/toys PUT /dogs/5/toys/2 GET /dogs/5 GET /dogs?fur=brown DELETE /dogs/5/toys/2 Give dog 5 a new toy Change something about his toy Get all data of dog 5 Get all dogs called Snoopy Take away his toy 200 NO CONTENTN/A request response
- 13. miredotmiredotmiredot REST Design Principles– Operations Choose your operation wisely! POST /dogs/5/toys PUT /dogs/5/toys/2 GET /dogs/5 GET /dogs?fur=brown DELETE /dogs/5/toys/2 Rule1: GET is readonly, has no side effects (, cacheable) Rule2: POST creates, PUT creates or updates Rule3: GET/PUT/DELETE are idempotent Give dog 5 a new toy Change something about his toy Get all data of dog 5 Get all dogs called Snoopy Take away his toy
- 14. miredotmiredotmiredot REST Design Principles Seehttp://www.miredot.com/blog/posts/rest-api-design-basic-rules/
- 15.
- 16. miredotmiredotmiredot REST API Issues GEThas a side-effect Never do this as this is often cached, pre-fetched, etc. Will cause hard to debug problems GET /accounts/3/balance à Wires €10 to Acme company GET /accounts/3/balance GET /accounts/3/balance GET /accounts/3/balance GET /accounts/3/balance à Wires €10 to Acme company à Wires €10 to Acme company …
- 17. miredotmiredotmiredot REST API Issues Datain query parameters POST https://api.twitter.com/statuses/update?status=Great%20to%20be%at%BeJUG POST //api.twitter.com/statuses/ { “status”: “Great to be at BEJUG” } PUT //api.twitter.com/statuses/4 { “status” : “Great to be at BEJUG” } Client-generated ID
- 18. miredotmiredotmiredot REST API Issues Verbsin the resource path Failed form of RPC /getAccount /createDirectory /group/update /dogs/4/bark GET PUT POST ?
- 19. miredotmiredotmiredot REST API Issues Howdo I make a dog bark? POST /dogs/5/bark POST /dogs/5/commands/ { “command”: “bark” } GET /dogs/5/commands/1 { “id”: 1, “command”: “bark”, “status”: “executed”, “time”: “2016-04-19” } Optional Reify the action à commands
- 20. miredotmiredotmiredot REST Design Principles– Other considerations Payloads (prefer JSON) Big vs small, field naming: be consistent (HATEOAS) Representation: one resource, multiple formats Accept and content-type headers Versioning Header, accept/content-type, URL Security Oauth, don’t invent your own
- 21. miredotmiredotmiredot Implementing REST inJava Jax-rs Spring-mvc
- 22. miredotmiredotmiredot Take care ofyour API It’s the user interface of your service Be API-centric, not Java-centric! Design your API with the whole team Review your API regularly Be consistent above all
- 23.
- 24. miredotmiredotmiredot How Important isAPI Documentation? For private APIs: VERY I DON’T want to look at your source code For public APIs: Didn’t find a word to describe Developers will hate your API, you and your company.
- 25. miredotmiredotmiredot Three Approaches Write ityourself Wikis, Word, Web-page Dedicated Wikis API Specification Language RAML, API Blueprint, Swagger Generate Miredot, Enunciate, Swagger, JsonDoc, APIDoc
- 26. miredotmiredotmiredot Write yourself 1. Word:DON’T 2. Wiki: avoid 3. readme.io, gelato.io: Nice docs, flexible REST/JSON-editor Import from Apiary, RAML, Swagger Hard to maintain Very hard to test (Never in sync with the implementation)
- 27.
- 28. miredotmiredotmiredot API Specification Language APIFirst: focus on design RAML, SwaggerSpec, API Blueprint (Apiary) Cross-language, cross-framework Hard to maintain Test your API through the spec: hard
- 29. miredotmiredotmiredot RAML Mulesoft, Anypoint platform YAMLbased, very modular Many tools, plugins: generate clients, documentation, parser, validator Varying quality API Specification Language Swagger (2.0) Smart Bear, Open API initiative Both a spec and tooling, also YAML Comes with core tooling (Swagger UI), several open source tools SwaggerUI: runtime component, interactive documentation More closely integration in your project (also Java)
- 30.
- 31.
- 32. miredotmiredotmiredot Generators Get documentation forfree Is my language / are my frameworks supported? Jax-rs, Spring-mvc / Jackson, Gson Is the output correct? Does it understand all my Java code (types, generics, frameworks)? Do I need to add anything to my code? Documentation always in sync with implementation Sit back and relax
- 33. miredotmiredotmiredot Enunciate One of thefirst generators for Java Supported frameworks Jax-rs Outputs Website, client libraries, WSDL, WADL Swagger Supported frameworks Jax-rs (very limited), Spring-mvc (via SpringFox) Requires its own annotations Outputs Website, interactive api client, client libraries, server stubs
- 34. miredotmiredotmiredot Miredot We were notsatisfied with existing generators Don’t support all Java constructs (generics, inheritance, …) or frameworks Hard to setup (hours/days) Java Support Full Jax-rs, Spring-mvc, Jackson, RestEasy, Guava, … Generics, inheritance, Optionals, Guava, … Outputs Website (static), Word, RAML Documentation quality reporting
- 35.
- 36. miredotmiredotmiredot Miredot Free for opensource, subscription for commercial projects Pay-per-endpoint Roadmap Documentation Quality Dashboard (Sonar-like) Version compatibility checking
- 37. miredotmiredotmiredot Final Words 1. Carefullydesign your API, you’ll be stuck with it for a long time 2. Don’t let documentation be an afterthought: start from day one 3. Use the many tools that are out there, they help a lot!
- 38.