Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Symfony UK: API Contracts using Open API

Symfony UK: API Contracts using Open API

Billie Thompson

October 19, 2016
Tweet

More Decks by Billie Thompson

Other Decks in Programming

Transcript

  1. Contents 1. Why do some APIs terrible? 2. API Contracts:

    Your Options 3. How to write OpenAPI Specifications 4. A Practical Example 5. Conclusion
  2. "organizations which design systems ... are constrained to produce designs

    which are copies of the communication structures of these organizations" — M. Conway
  3. "If you have four groups working on a compiler, you'll

    get a 4-pass compiler" — Eric S Raymond
  4. Sit in a room with the stake holders And write

    down the results (In a computer readable document)
  5. The Why! » Learn about requirements » Share Expectations »

    Humanizing teams creates respect » Living Documentation
  6. Things to consider (It's got to do these in PHP)

    » Generate Clients » Validate Standard » Documentation Generation » Pleasant Editor
  7. 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.
  8. 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
  9. OpenAPI Specification » Generate Clients: Yes, lots for PHP and

    other languages » Validate Standard: Yes » Documentation Generation: Yes, loads » Pleasant Editor: Yes, lots
  10. Some History » ~2011 - Swagger Released based on JSON

    Schema » ~2014 - v2 Released » January 1st 2016 - Swagger becomes OpenAPI Specification
  11. 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)
  12. { "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" ],
  13. {"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" } } } } } } },
  14. {"definitions": { "Pet": { "type": "object", "required": [ "id", "name"

    ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } } }
  15. Demo Checklist » The swagger file for this Example »

    Generating Clients » The Implementation » Validating the Spec » The Documentation UI
  16. 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)
  17. 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/