PiterPy #3 talk (Video: https://youtu.be/bCwSyyygSmM). Some points on RAML, general overview and takeaways based on a real project. Presented with Dmitry Nazarov https://ru.linkedin.com/in/aspectmkn8rd/en (Part 2, as mentioned in contents)

1. API Docs Made Right
or yet another API modelling rant

2. Meta: About Us
Dmitry Nazarov
Vladimir Shulyak

3. Meta: Contents
Part 1: Overview
Why you should care
History of API DLs
API DLs overview
Part 2: Technical
The Joel Boris test
Takeaways

4. 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

5. What’s an API DL?

6. 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

7. So why do we need those fancy
API DLs?

8. 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

9. 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

10. It’s all started a while ago...

12. ...with XML goodness
WSDL
WADL
+XSD

13. 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>

15. 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

16. API DLs Hype Curve
You are here

17. Swagger vs RAML

18. Swagger

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

20. 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"

21. Swagger Community and Tooling
Highly active community
Used by: Hootsuite, Zalando, possibly you
Tools:
● Swagger UI. Documenation generation
● Swagger Editor. Clould editor

22. RAML

23. 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

24. 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

25. 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

26. ...But which one should I use?

27. 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

28. 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

29. The Boris Test
9 Steps to better API documentation

31. 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

32. 1. Do you use hypermedia type to define
responses?
HAL
Collection+JSON
JSON Hyperschema
Plenty of them suits RAML
JSON-LD
Hydra
Siren

33. 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

34. 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"
]
}

35. A specification for building APIs in JSON
Achieving shared expectations
Free from limitations of contestants (HAL, ..)
JSON API

36. 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"
}

37. 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

38. 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?

39. 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/..)

40. 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

41. 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

42. 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

43. 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

44. 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

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

46. 9. Does your API itself follows best
practices?
● stable
● flexible
● secure
● <..>
● properly versionated
● throttled
● fast

47. 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

48. Grazie mille