Slide 1
Slide 1 text
Fake It Before
You Make It
Mocking Your Way to
Better HTTP APIs
Slide 2
Slide 2 text
Slides, Notes, Examples
http://BetterAPIs.com/
Slide 3
Slide 3 text
Terminology
Slide 4
Slide 4 text
REST
Standard
Architectural Style
Constraints
REST-like HTTP APIs
Slide 5
Slide 5 text
API Contract
Client ↔ Provider
Interface Specification
SLA, ToS, Limits, Pricing,
etc.
Slide 6
Slide 6 text
JSON
JavaScript Object
Notation
{
"things": [
"foo",
"bar"
],
"message": "Hello, World!"
}
Slide 7
Slide 7 text
JSON Schema
{
"title": "Example Schema",
"type": "object",
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"age": {
"description": "Age in years",
"type": "integer",
"minimum": 0
}
},
"required": ["firstName", "lastName"]
}
Slide 8
Slide 8 text
YAML
Serialization format
(More) human-readable
Subset of JSON
Borad Language Support
Slide 9
Slide 9 text
This Talk
Slide 10
Slide 10 text
Requirement
Accept POST
Return OK / validation errors
Slide 11
Slide 11 text
Implementation
Accept POST
Return OK / validation errors
Slide 12
Slide 12 text
“That's not really what we
wanted.”
ಠ_ಠ
Slide 13
Slide 13 text
The Difference
We provided They expected
* simplified example
{
"valid": false,
"errors": {
"field_1": "too short"
"field_2": "required",
}
}
{
"valid": false,
"errors": [
{
"field": "field_1"
"error": "too short",
},
{
"error": "required"
"field": "field_2",
}
]
}
Slide 14
Slide 14 text
How can we do better?
Slide 15
Slide 15 text
API Specification
Machine Readable
Basis of “Contract”
Slide 16
Slide 16 text
History
WSDL, WADL
Slide 17
Slide 17 text
For REST(ish) APIs
Slide 18
Slide 18 text
Swagger ➡️ OpenAPI
JSON Specification
Rich Ecosystem
2.0: YAML ➡️ JSON
OpenAPI Initiative
Slide 19
Slide 19 text
Swagger Example
swagger: '2.0'
info:
version: '1.0.0'
title: Fake Better API
description: >
This is a basic example API for our talk at http://betterapis.com.
termsOfService: http://betterapis.com/terms/
contact:
name: API Team
email: [email protected]
url: http://betterapis.com/contact/
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
host: api.betterapis.com
basePath: /
securityDefinitions: {}
schemes:
- http
consumes:
- application/json
produces:
...
Slide 20
Slide 20 text
Swagger Example Contd.
paths:
/foo:
get:
operationId: listFoo
produces:
- application/json
parameters:
- name: limit
in: query
type: integer
description: maximum number of foo to return
responses:
200:
description: List all foo
schema:
type: array
items:
$ref: '#/definitions/Foo'
...
definitions:
Foo:
title: Foo
description: An example type of object
type: object
properties:
Slide 21
Slide 21 text
RAML
YAML Specification
Modeling
Inheritance
1.0 Just Released
RAML Workgroup
Slide 22
Slide 22 text
RAML Example
#%RAML 0.8
title: Fake Better API
version: 1.0.0
documentation:
- title: Fake Better API
content: Basic example API for our talk at http://betterapis.com.
baseUri: http://api.betterapis.com/
schemas:
- Foo-array: |
{
"type": "array",
"items": {
"id": "Foo",
"title": "Foo",
"description": "An example type of object",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"score": {
"type": "integer",
"format": "int32"
}
...
Slide 23
Slide 23 text
RAML Example Contd.
/foo:
/{fooId}:
uriParameters:
fooId:
description: ID of the foo
type: string
required: true
displayName: fooId
get:
displayName: getFooByID
responses:
200:
description: Foo with the specified ID
404:
description: Foo with specified ID not found
get:
displayName: listFoo
responses:
200:
description: List all foo
body:
application/json:
schema: Foo-array
...
`
Slide 24
Slide 24 text
API Blueprint
Documentation as Specification
MarkDown + Extensions
Node & .Net
Open RFC Process
Slide 25
Slide 25 text
API Blueprint Example
FORMAT: 1A
HOST: http://api.betterapis.com/
# Fake Better API
This is a basic example API for our talk at http://betterapis.com.
# Foo [/foo{?limit}]
## listFoo [GET]
+ Parameters
+ limit (, optional) -
maximum number of foo to return
+ Default: 10
+ Response 200 (application/json)
List all foo
+ Attributes (array[Foo])
...
Slide 26
Slide 26 text
API Blueprint Example Contd.
# Foo [/foo]
## putFoo [PUT]
+ Request (application/json)
+ Attributes (Foo)
+ Response 200 (application/json)
Updates a foo
+ Attributes (Dynamic)
+ Response 400
Invalid foo data
## postFoo [POST]
+ Request (application/json)
+ Attributes (Foo)
+ Response 200 (application/json)
...
Slide 27
Slide 27 text
Comparison
User-base
Tooling
Language
It Depends...
Slide 28
Slide 28 text
“How do we create the
specification?”
Slide 29
Slide 29 text
“We have a specification; now
what?”
Slide 30
Slide 30 text
Documentation
Slide 31
Slide 31 text
Mocking
Slide 32
Slide 32 text
Testing
Slide 33
Slide 33 text
Code Generation
Slide 34
Slide 34 text
Contract-first
Then implement
Slide 35
Slide 35 text
Spec
Build / Update
Publish
Mock
Fake it ➡️
Make it
API
Implement
Validate
Slide 36
Slide 36 text
Demo
Slide 37
Slide 37 text
Python-specific
API Blueprint
plueprint
Swagger / OpenAPI
Multiple parsers
Connexion
RAML
ramlfications
griffin (alpha)
RAMSES
Slide 38
Slide 38 text
Resources
http://BetterAPIs.com/
Further Reading
Slide 39
Slide 39 text
Thank You!
Ian
[email protected]
@izcoder
Slides, notes, &
examples:
Questions?
Dave
[email protected]
@tylerdave
http://BetterAPIs.com/