API Docs Made Right / RAML - Swagger rant

API Docs Made Rightor yet another API modelling rant

Meta: About Us

Dmitry Nazarov

Vladimir Shulyak

Meta: Contents

Part 1: Overview

Why you should care

History of API DLs

API DLs overview

Part 2: Technical

The Joel Boris test

Takeaways

Meta: Assumptions

Either you:

● Haven’t heard of API DLs / Not convinced it’s useful● Having trouble choosing suitable DL● Are using API DL in your project

We tried to cover all the basics

What’s an API DL?

API Description Languages 101

A structured document in YAML, JSON, Markdown with API definitions

API definition approaches:

● Top-down – create API definition first, in a separate release cycle● Bottom-up – create API first, then describe/auto-generate definition

Mocking – a way to create a mock API from its definition

So why do we need those fancy API DLs?

Benefits from business POV

Efficient and predictable collaboration with API model (Top-Down approach):

● Expectation gaps between API producers and consumers● External teams/subcontractors have clear specs

API modelling helps in team load distribution (Top-Down approach):

● Any available party can start modelling the API, others join later● Mocking enables writing code before the actual implementation is ready

Benefits from developer POV

Interfaces/Constraints first leads to better code

More potential issues discovered with iterative API design as a first stage

Natural way to document your project

It’s all started a while ago...

...with XML goodness

WSDL

WADL

+XSD

WADL example

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<resources base="http://api.search.yahoo.com/NewsSearchService/V1/">

<resource path="newsSearch">

<method name="GET" id="search">

<request>

<param name="appid" type="xsd:string" style="query" required="true"/>

<param name="query" type="xsd:string" style="query" required="true"/>

<param name="type" style="query" default="all">

<option value="all"/>

<option value="any"/>

<option value="phrase"/>

</param>

<param name="results" style="query" type="xsd:int" default="10"/>

<param name="language" style="query" type="xsd:string"/>

</request>

<response status="200">

<representation mediaType="application/xml" element="yn:ResultSet"/>

</response>

</method>

</resource>

</resources>

</application>

A.S. Years: After Swagger Era

Swagger 1.0

RAML 0.8 RAML 1.0 RC2

Swagger 1.2 Swagger 2.0

2011 2012 2013 2014 2015 2016

RAML 1.0 RC1

Swagger 1.1

API Blueprint 1A API Blueprint 1A5 API Blueprint 1A9

Open API

API DLs Hype Curve

You are here

Swagger vs RAML

Swagger

Swagger / Open API

Started as a tool for Wordnik

Model historically in JSON and YAML later

Both Bottom-Up (1.0) and Top-Down (1.0/2.0) approaches to modelling

Reuse: referencing, but capabilities are superficial

Nowadays a base of Open API initiative (Google, IBM, Intuit, Microsoft)

Swagger 2.0 Example

paths: /pets: get: description: "Returns all pets" produces: - "application/json" responses: "200": description: "A list of pets." schema: type: "array" items: $ref: "#/definitions/Pet"

definitions: Pet: type: "object" required: - "id" - "name" properties: id: type: "integer" format: "int64" name: type: "string" tag: type: "string"

Swagger Community and Tooling

Highly active community

Used by: Hootsuite, Zalando, possibly you

Tools:

● Swagger UI. Documenation generation● Swagger Editor. Clould editor

RAML

RAML

Created by MuleSoft, but has a workgroup

YAML based

Top-down approach

Data types/schemas definition within RAML (1.0)

Reuse: resource types and traits

RAML 1.0 Example

types:

Pet:

type: object

required:

- id

- name

properties:

id: number

name: string

tag: string

/pets:

get:

description: “Returns all pets”

responses:

200:

description: “A list of pets”

body:

application/json:

schema: Pet

RAML Community and Tooling

Not as active as Swagger

Used by: Spotify, VMWare, less popular than Swagger, but has traction anyway

Tools: later on in this talk

...But which one should I use?

Swagger is great, but we bet on RAML

Swagger has a great community and tooling

But RAML has great tools as well!

RAML embraces pattern usage and code reuse

Used RAML in 3 big projects, happy so far

Any DL is better than no DL

The Joel Test: 12 Steps to Better Code

It’s a classic list of simple questions

You’re getting clear overview of how good your software team is

We had an idea to make something similar

The Boris Test9 Steps to better API documentation

1. Do you use hypermedia type to define responses?

Data Definition Languages (DDLs): data modelling, data validation

Hypermedia Types: a way to link API endpoints, documentation, potential actions, and related endpoints

1. Do you use hypermedia type to define responses?

HAL

Collection+JSON

JSON Hyperschema

Plenty of them suits RAML

JSON-LD

Hydra

Siren

Based on the concepts from XML Schemas (XSD)

..but JSON-based

Self-describing, readable

Same serialization/deserialization tools both for the schema and data

JSON Schema

JSON Schema Response Example

{ "title": "Example Schema", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": [ "firstName", "lastName" ]}

A specification for building APIs in JSON

Achieving shared expectations

Free from limitations of contestants (HAL, ..)

JSON API

JSON API: Example response

"relationships": { "author": { "links": { "self": "http://example.com/articles/1/relationships/author", "related": "http://example.com/articles/1/author" }, "data": { "type": "people", "id": "9" } }, "comments": { <..> }},"links": { "self": "http://example.com/articles/1"}

2. Do you have your API design tools set up?

Editing RAML: autocomplete, test, visualize, validate

IDEs (API Workbench, API Designer)plugins (YAML)

Editing JSON Schemas: generators

For end user

● the structure matches your API

● helps to start working with API quickly

..and for developer:

● sharing schemas

● getting schemas via http / as a submodule, reusing them

3. Do you organize your documentation properly?

4. Do you take advantage of reusable RAML constructions?

Keeping it DRY matters

● includes: inline one files to another● resource types: reuse structures of methods● traits: reuse attributes (auth/search/sort/..)

5. Is your documentation interactive for end user?

API Console: visualize structure, provide in-browser testing

API Notebook: JS scripting workspace; versioned, forkable and shareable API use cases

Speeds up the development

6. Does your whole team collaborate on API design?

The usual issues in flow of team interaction

It needs to be done async-way

You should also be able to walk any direction

6. Does your whole team collaborate on API design?

The role of API documentation here: providing clear and persistent feedback loop

Mocking as an essential part

Which is easy for you

7. Do you automate test & validation of requests and responses?

Not enough to just have doc and schemas

Perform validation automatically on test run

Schemas as a linking element of the system

7. Do you automate test & validation of requests and responses?

Data for test requests (and examples):

● writing manually (fixtures)● generating it automatically (factories)

What’s wrong with fixtures

..and with factories

8. Do you have your documentation up to date and easily accessible to the team?

Private and public APIs

Builded (into html), served (via http)

..on demand locally, automatically on CI..

Automate to the max (+ autoreload, autoopen)

9. Does your API itself follows best practices?

● stable

● flexible

● secure

● <..>

● properly versionated

● throttled

● fast

Takeaways

Lots of daily pain removed

Good for new devs joining: dive fast, water is clear

Manually write JSON requests/responses less, generate it more

Attention to maintentence. The whole thing gets outdated

Use the tools and automate everything to be productive

Grazie mille