API Docs Made Right / RAML - Swagger rant
-
Upload
vladimir-shulyak -
Category
Software
-
view
575 -
download
2
Transcript of 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