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.
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)
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
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
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
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
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)
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!