RESTFul API Design and Documentation - an Introduction
•
6 gefällt mir•1,643 views
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.
Empfohlen
Weitere ähnliche Inhalte
Was ist angesagt?
Was ist angesagt? (20)
Andere mochten auch
Andere mochten auch (15)
Ähnlich wie RESTFul API Design and Documentation - an Introduction
Ähnlich wie RESTFul API Design and Documentation - an Introduction (20)
Kürzlich hochgeladen
Kürzlich hochgeladen (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!