API Contracts using Open API Billie Thompson @PurpleBooth https://github.com/PurpleBooth/book-store 

Contents 1. Why are some APIs terrible? 2. API Contracts: Your Options 3. How to write OpenAPI Specifications 4. A Practical Example 5. Conclusion 

Why do some APIs terrible? Even though they don't have downtime, or bugs 

Conway's Law 

"organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations" — M. Conway 

"If you have four groups working on a compiler, you'll get a 4-pass compiler" — Eric S Raymond 

Changing communication between stakeholders 

Sit in a room with the stake holders And write down the results (In a computer readable document) 

The Why! » Learn about requirements » Share Expectations » Humanising teams creates respect » Living Documentation 

A Contract Options for defining one 

Things to consider (It's got to do these in PHP) » Generate Clients » Validate Standard » Documentation Generation » Pleasant Editor 

Your Options » RAML » API Blueprint » OpenAPI/Swagger (JSON Schema + Operations) 

RAML 

No content

RAML » Generate Clients: Yes, roughly 1 choice per language » Validate Standard: No (not in PHP anyway) » Documentation Generation: Yes, loads » Pleasant Editor: Yes Note: Weird split between version 0.8, 1.0. 

API Blueprint 

No content

API Blueprint » Generate Clients: Yes, roughly 2 generators (poor generally) » Validate Standard: Yes » Documentation Generation: Yes, 3 or 4 things » Pleasant Editor: Yes Note Blueprint was sponsored by Apiary, who have now thrown themselves behind OpenAPI Specification 

OpenAPI Specification 

No content

OpenAPI Specification » Generate Clients: Yes, lots for PHP and other languages » Validate Standard: Yes » Documentation Generation: Yes, loads » Pleasant Editor: Yes, lots 

No content

Some History » ~2011 - Swagger Released based on JSON Schema » ~2014 - v2 Released » January 1st 2016 - Swagger becomes OpenAPI Specification 

Swagger is awesome but: » Don't use swaggers YAML format. » Inheritance Doesn't work well » Nulls aren't well supported (It's still pretty awesome though) 

How to write Open API Specifications 

{ "swagger": "2.0", "info": { }, "paths": { }, "definitions": { } } 

{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "Swagger API Team" } }, "consumes": [ "application/json" ], "produces": [ "application/json" ], 

{"paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "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" } } } } 

A Practical Example Mandatory Symfony Example 

Demo Checklist » The swagger file for this Example » Generating Clients » The Implementation » Validating the Spec » The Documentation UI 

The tooling rocks! 

What to take away 

Questions? @PurpleBooth » https://github.com/PurpleBooth/book-store » http://apievangelist.com/2016/09/16/a-look-at-the-state-of-api- documentation-solutions/ » https://github.com/janephp/openapi » https://github.com/fitbug/guzzle-swagger-validation-middleware » https://github.com/OAI/OpenAPI-Specification » http://swagger.io/swagger-ui/ » http://editor.swagger.io/