restful api design and documentation - an introduction

miredotmiredot

miredotRESTful API Design and Documentation – an Introduction

BeJUG April 2016

miredotmiredotmiredot

Agenda

REST – What and Why?Basic REST Design PrinciplesDocumenting a REST APIQuick DemosMiredot

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

*

*This is not the actual Twitter API **This is

**


REST – What and Why?

REpresentational State TransferThings/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)

miredotmiredot


REST Design Principles

Religiously RESTful vs REST-like

Goals1. Easy to use API2. Predictable behavior3. Works with existing infrastructure (proxies, browsers)

Don’t think Java, think API first!


REST Design Principles – URI / Resource

https://api.acme.com/petstore/dogs/5/toys/2/parts

base URL

all the dogs

dog with id=5toy with id=2

all the toys of dog 5all the parts of toy 2

?material=plastic

Rule1: Plural for collections, ID for single elementRule2: No verbs! ../petstore/dogs/addRule3: Query params only for meta-info (filtering, format)

extra info


REST Design Principles – Operations

Choose your operation wisely!

POST /dogs/5/toys PUT /dogs/5/toys/2GET /dogs/5GET /dogs?fur=brownDELETE /dogs/5/toys/2

Give dog 5 a new toyChange something about his toyGet all data of dog 5Get all dogs called SnoopyTake away his toy

POST = Create

PUT = Update (or create)GET = Read

DELETE = Delete






201 CREATED “2”

{ “name”: “chicken” }

request response






200 OK { “name”: “duck” }

request response






200 OK { “name”: “Snoopy” “favouriteToy”: 2 }

N/A request response






200 OK [{ “name”: “Scooby Doo” }, { “name”: “Lassie” }]

N/A request response






200 NO CONTENT N/A request response





Rule1: GET is readonly, has no side effects (, cacheable)Rule2: POST creates, PUT creates or updates Rule3: GET/PUT/DELETE are idempotent



REST Design PrinciplesSee http://www.miredot.com/blog/posts/rest-api-design-basic-rules/

miredotmiredot


REST API Issues

GET has a side-effectNever 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




à Wires €10 to Acme company

à Wires €10 to Acme company

…


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


REST API Issues

Verbs in the resource path

Failed form of RPC

/getAccount /createDirectory

/group/update /dogs/4/bark

GET PUT POST ?


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” }

OptionalReify the action à commands


REST Design Principles – Other considerations

Payloads (prefer JSON)Big vs small, field naming: be consistent(HATEOAS)

Representation: one resource, multiple formatsAccept and content-type headers

VersioningHeader, accept/content-type, URL

SecurityOauth, don’t invent your own


Implementing REST in JavaJax-rs

Spring-mvc


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

miredotmiredot


How Important is API Documentation?

For private APIs: VERYI DON’T want to look at your source code

For public APIs: Didn’t find a word to describeDevelopers will hate your API, you and your company.


Three Approaches

Write it yourselfWikis, Word, Web-pageDedicated Wikis

API Specification LanguageRAML, API Blueprint, Swagger

GenerateMiredot, Enunciate, Swagger, JsonDoc, APIDoc


Write yourself

1.  Word: DON’T

2.  Wiki: avoid

3.  readme.io, gelato.io: Nice docs, flexibleREST/JSON-editorImport from Apiary, RAML, Swagger

Hard to maintainVery hard to test(Never in sync with the implementation)

miredotmiredot


API Specification Language

API First: focus on design

RAML, SwaggerSpec, API Blueprint (Apiary)

Cross-language, cross-framework

Hard to maintainTest your API through the spec: hard


RAML

Mulesoft, Anypoint platform

YAML based, very modular

Many tools, plugins: generate clients, documentation, parser, validator

Varying quality


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)


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 implementationSit back and relax


Enunciate

One of the first generators for Java

Supported frameworksJax-rs

OutputsWebsite, client libraries, WSDL, WADL

Swagger

Supported frameworksJax-rs (very limited), Spring-mvc (via SpringFox)Requires its own annotations

OutputsWebsite, interactive api client, client libraries, server

stubs


Miredot

We were not satisfied with existing generatorsDon’t support all Java constructs (generics, inheritance, …) or frameworksHard to setup (hours/days)

Java SupportFull Jax-rs, Spring-mvc, Jackson, RestEasy, Guava, … Generics, inheritance, Optionals, Guava, …

OutputsWebsite (static), Word, RAML

Documentation quality reporting


Demo

Swagger, Miredot


Miredot

Free for open source, subscription for commercial projectsPay-per-endpoint

RoadmapDocumentation Quality Dashboard (Sonar-like)Version compatibility checking


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!

miredotmiredot

www.miredot.com

[email protected] [email protected]

miredotThank you!try

restful api design and documentation - an introduction

Software