RESTFul API Design and Documentation - an Introduction
•
6 recomendaciones•1,643 vistas
The world is interconnected by APIs more than ever. It is almost unimaginable to develop any kind of software today that doesn't either offer or invoke a web-API. The majority of (new) APIs offer a REST + JSON interface and the Java platform is very well equipped to develop such APIs. In our talk we'll quickly recap what REST exactly means and we'll give a set of pointers to help with RESTful API-design. Since we are creating an open API that any customer should be able to use from any programming language, technology-neutral documentation of this API is key. We can't stress this enough. We will present a high-level overview of different possibilities of documenting APIs, ranging from the API-first approach (RAML, Apiary, etc.) to generators (Swagger, Enunciate, etc.), including Miredot.
Recomendados
Más contenido relacionado
La actualidad más candente
La actualidad más candente (20)
Destacado
Destacado (15)
Similar a RESTFul API Design and Documentation - an Introduction
Similar a RESTFul API Design and Documentation - an Introduction (20)
Último
Último (20)
RESTFul API Design and Documentation - an Introduction
- 1. miredotmiredot miredot RESTful API Design and Documentation – an Introduction BeJUG April 2016
- 2. miredotmiredotmiredot Agenda REST – What and 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 – What and 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)
- 5. miredotmiredotmiredot REST Design Principles Religiously RESTful 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 See http://www.miredot.com/blog/posts/rest-api-design-basic-rules/
- 15. miredotmiredot
- 16. miredotmiredotmiredot REST API Issues GET has 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 Data in 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 Verbs in the resource path Failed form of RPC /getAccount /createDirectory /group/update /dogs/4/bark GET PUT POST ?
- 19. miredotmiredotmiredot REST API Issues How do 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 in Java Jax-rs Spring-mvc
- 22. miredotmiredotmiredot Take care of your 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. miredotmiredot
- 24. miredotmiredotmiredot How Important is API 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 it yourself 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. miredotmiredot
- 28. miredotmiredotmiredot API Specification Language API First: 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 YAML based, 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)
- 32. miredotmiredotmiredot Generators Get documentation for free 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 the first 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 not satisfied 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
- 36. miredotmiredotmiredot Miredot Free for open source, subscription for commercial projects Pay-per-endpoint Roadmap Documentation Quality Dashboard (Sonar-like) Version compatibility checking
- 37. miredotmiredotmiredot Final Words 1. Carefully design 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!