Symfony UK: API Contracts using Open API

Transcript

1. API Contracts using Open API Billie Thompson @PurpleBooth https://github.com/PurpleBooth/book-store
2. Contents 1. Why do some APIs terrible? 2. API Contracts: Your Options 3. How to write OpenAPI Specifications 4. A Practical Example 5. Conclusion
3. Why do some APIs terrible? Even though they don't have downtime, or bugs
4. Conway's Law
5. "organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations" — M. Conway
6. "If you have four groups working on a compiler, you'll get a 4-pass compiler" — Eric S Raymond
7. Changing communication between stakeholders
8. Sit in a room with the stake holders And write down the results (In a computer readable document)
9. The Why! » Learn about requirements » Share Expectations » Humanizing teams creates respect » Living Documentation
10. A Contract Options for defining one
11. Things to consider (It's got to do these in PHP) » Generate Clients » Validate Standard » Documentation Generation » Pleasant Editor
12. Your Options » RAML » API Blueprint » OpenAPI/Swagger (JSON Schema + Operations)
13. RAML
15. 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.
16. API Blueprint
18. 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
19. OpenAPI Specification
21. OpenAPI Specification » Generate Clients: Yes, lots for PHP and other languages » Validate Standard: Yes » Documentation Generation: Yes, loads » Pleasant Editor: Yes, lots
23. Some History » ~2011 - Swagger Released based on JSON Schema » ~2014 - v2 Released » January 1st 2016 - Swagger becomes OpenAPI Specification
24. 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)
25. How to write Open API Specifications
26. { "swagger": "2.0", "info": { }, "paths": { }, "definitions": { } }
27. { "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" ],
28. {"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" } } } } } } },
29. {"definitions": { "Pet": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } } }
30. A Practical Example Mandatory Symfony Example
31. Demo Checklist » The swagger file for this Example » Generating Clients » The Implementation » Validating the Spec » The Documentation UI
32. The tooling rocks!
33. Convince your boss » Remember communication structures drive the solution » Define swagger in annotations » Be excited and do a talk at work (or at Symfony meet ups)
34. 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/