Documented and Tested Microservices For Fun And Profit

Oliver Trosien, ePages GmbH

WTF is a "REST endpoint"?
- Roy Fielding

Documenting REST APIs

apihandyman.io

How RESTful are you?

How RESTful do you
want to be?

Interface Description Languages

• WSDL (2001)
• | WADL (2009)
• | Swagger (2009)
• | RESTdesc (2010)
• | I/O Docs (2011)
• | JSON Home (2012)
• | RAML (2013)
• | API Blueprint (2013)
• | JSON Hyper-Schema (2013)
• | Hydra (2014, draft)
• | ALPS (2014, draft)
• | UBER (2015, draft)
• | CPHL (2015, brain-storming)
• ..

Media Types

• Plain-old XML
• | Proprietary JSON
• | HAL (2011)
• | JSON-LD (2011)
• | Collection+JSON (2011)
• | JSON API (2013)
• | Hydra (2014)
• | Mason (2014, draft)
• | SIREN (2015, draft)
• ..

HAL

					
{
  "_links": {
    "self": {
      "href": "http://otrosien:8081/pizzas"
    }
  },
  "_embedded": {
    "pizzas": [
      {
        "name": "Pizza Salami",
        "description": "The classic"
      }
    ]
  }
}
					
					

Spring-Data-REST

Spring WebMVC Spring-Data Spring-HATEOAS

• Repositories as resources with CRUD operations
• Supports HAL + ALPS + JSON Schema
• Ties your REST API to your data model

olivergierke/spring-restbucks

Follow your nose API

• Single well-known entry point
• Resources discoverable via link relations

Documentation style

• Focus on problem domain
• Focus on relations
• Be consistent
• Focus on URIs
• Repeating the obvious

The ePizza system

ePages-de/rnd-microservices-handson

Demo

Learnings

• IDL standards are still evolving
• Tool-support (usually) still poor
• Be correct, complete and current

Thank you!

For more info, feel free to contact us
@epagesdevs
epages.com/devjobs
otrosien@epages.com
ePages-de/codetalks2015