![API specification languages
4
#%RAML 1.0
title: Pet Shop
uses:
NewLibrary:
NewLibrary.raml
version: v1
baseUri: /shop
types:
Mammal:
type:
NewLibrary.Pet
Bird:
type:
NewLibrary.Pet
properties:
wingLength:
number
swagger: "2.0",
info: {…},
host: "petstore.swagger.io",
basePath: "/v2",
tags: […],
schemes: […],
paths: [{
/pet: {
post: {
tags: {
summary "Add a new
pet to the store",
description ""},
operationId:
{"addPet"}
}]
}]
FORMAT: 1A
# Pets
Petstore!
## Pets Collection [/pets]
### List All Pets [GET]
+ Response 200
(application/json)
{
"name": "Buckbeak",
"species": "Hippogriff",
}](https://image.slidesharecdn.com/2019-08-23apicontracttesting-200612223513/85/2019-08-23-API-contract-testing-with-Dredd-4-320.jpg)
![Contracts drive tooling
6
Supported by automated tooling
- Contract → application
controllers
- Contract → End-point testing
- Contract → Documentation
- Contract → SDK stubs
- Contract → Access control
{
"swagger":"2.0",
"host":"petstore.swagger.io",
"/pet/{petId}":{
"get":{
"operationId":"getPetById",
"parameters":[ ],
"responses":{ }
}
}
}](https://image.slidesharecdn.com/2019-08-23apicontracttesting-200612223513/85/2019-08-23-API-contract-testing-with-Dredd-6-320.jpg)
![Example: Interactive Docs
7
widdershins
swagger-ui
{
"swagger":"2.0",
"host":"petstore.swagger.io",
"/pet/{petId}":{
"get":{
"operationId":"getPetById",
"parameters":[ ],
"responses":{ }
}
}
}](https://image.slidesharecdn.com/2019-08-23apicontracttesting-200612223513/85/2019-08-23-API-contract-testing-with-Dredd-7-320.jpg)
![Binding contract to controller
17
getPetById('/pet/:PetId',
(req, res, next) => {
validate(PetId)
myDB.get(new Resource('/pet', petId
(err, pet) => {
if(err) next(err)
res.json(pet.data)
})
})
{
"swagger":"2.0",
"host":"petstore.swagger.io",
"/pet/{petId}":{
"get":{
"operationId":"getPetById",
"parameters":[ ],
"responses":{ }
}
}
}
middleware: swagger-node](https://image.slidesharecdn.com/2019-08-23apicontracttesting-200612223513/85/2019-08-23-API-contract-testing-with-Dredd-17-320.jpg)
2019-08-23 API contract testing with Dredd
- 1. API Contract testing Ryan M Harrison August 23, 2019
- 2. More testing, why!?...just let me code 2 Aside: If you need some help with the math, let me know, but that should be enough to get you started! Huh? No, I don't need to read your thesis, I can imagine roughly what it says.
- 3. API specification languages 3 OAS (Open API Spec) AKA: Swagger API Blueprint RAML RESTful API Modeling Language
- 4. API specification languages 4 #%RAML 1.0 title: Pet Shop uses: NewLibrary: NewLibrary.raml version: v1 baseUri: /shop types: Mammal: type: NewLibrary.Pet Bird: type: NewLibrary.Pet properties: wingLength: number swagger: "2.0", info: {…}, host: "petstore.swagger.io", basePath: "/v2", tags: […], schemes: […], paths: [{ /pet: { post: { tags: { summary "Add a new pet to the store", description ""}, operationId: {"addPet"} }] }] FORMAT: 1A # Pets Petstore! ## Pets Collection [/pets] ### List All Pets [GET] + Response 200 (application/json) { "name": "Buckbeak", "species": "Hippogriff", }
- 5. API specification languages 5 Open API Spec API Blueprint RAML Sponsor Open API Initiative (SmartBear) Apiary (Oracle) RAML Workgroup (Mulesoft) Format JSON Markdown (apib) YAML Schema JSON Schema MSON License Apache 2.0 MIT Apache 2.0 API Gateway support AWS API Gateway Apigee (Google) 3scale (Rehat)
- 6. Contracts drive tooling 6 Supported by automated tooling - Contract → application controllers - Contract → End-point testing - Contract → Documentation - Contract → SDK stubs - Contract → Access control { "swagger":"2.0", "host":"petstore.swagger.io", "/pet/{petId}":{ "get":{ "operationId":"getPetById", "parameters":[ ], "responses":{ } } } }
- 7. Example: Interactive Docs 7 widdershins swagger-ui { "swagger":"2.0", "host":"petstore.swagger.io", "/pet/{petId}":{ "get":{ "operationId":"getPetById", "parameters":[ ], "responses":{ } } } }
- 8. Tooling 8 Open API Spec Authoring / Editor swagger-editor API docs swagger-ui, widdershins, spectacle, redoc Testing dredd Mock server prism SDK stubs swagger-codegen Contract->Controller swagger-node
- 9. Testing > Contract ● Authoring / Editor ● Interactive API docs ● Testing ○ Contract^ ■ Producer-side (server-side) ■ Consumer-side (client-side) ○ Behavior ● Mock server ● API Stubbing ● Contract-to-Controller integration ● Spec conversion 9
- 10. Testing > Contract ● Shared understanding >> Business logic ● Contract is the “source of truth” 10
- 11. DEMO: Dredd w/ amida-auth-service 11 Follow along: https://github.com/amida-tech/amida-auth- microservice/tree/devreview-20190823-dredd Gotchas ● Must manage state in hooks ○ Or work-around using `--sorted` ● Dredd still doesn’t support Java hooks^ ● Assume 1:1 Request:Response, i.e. multi-response request not fully supported^ ● Incompatibility between OAS Schema Objects and JSON Schema
- 12. Dredd gotchas 12 ● Must use hooks for auth flows ● Must manage state in hooks ○ Or quick-and-dirty work-around using `--sorted` ● Dredd still doesn’t support Java hooks^ ● Assume 1:1 Request:Response, i.e. multi-response request not fully supported^ ● Some incompatibility between OAS Schema Objects and JSON Schema, i.e. $ref be your bane
- 13. Testing ● Authoring / Editor ● Interactive API docs ● Testing ○ Contract^ ■ Producer-side (server-side) ■ Consumer-side (client-side) ○ Behavior ● Mock server ● API Stubbing ● Contract-to-Controller integration ● Spec conversion 13
- 14. Testing > Contract > Consumer-side 14 Producer-sideConsumer-side
- 15. Testing > Behavioral 15 ● karate (Java) ● Behave (Python) ● RESTinstance (JS) ● apickli (JS) Scenario: Create user, view list, delete user Given url_users And request {username: <>, password: <>} When method post Given url_users When method get Given url_users And request {id: response.id} When method delete
- 16. Ponderings ● Binding API contract to controllers, e.g. swagger-node? ● Where to include validation rules? ○ Door #1: Unit tests ⇒ No examples for API consumer ○ Door #2: Contract ⇒ Bloated contract ○ Door #3: Behavior ⇒ Unclear “user flow” ● Postman collections vs API contracts ○ Postman doesn’t seem to support comparison to example^ ○ Cannot export from Postman to any API Spec^ ● Transformers: Good open source one? ○ Proprietary: https://www.apimatic.io/transformer/ 16
- 17. Binding contract to controller 17 getPetById('/pet/:PetId', (req, res, next) => { validate(PetId) myDB.get(new Resource('/pet', petId (err, pet) => { if(err) next(err) res.json(pet.data) }) }) { "swagger":"2.0", "host":"petstore.swagger.io", "/pet/{petId}":{ "get":{ "operationId":"getPetById", "parameters":[ ], "responses":{ } } } } middleware: swagger-node
- 18. Questions?