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

PHP London: API Contracts using Open API

PHP London: API Contracts using Open API

3a1c6ce62064c58e2420e9e27c125716?s=128

Billie Thompson

February 02, 2017
Tweet

More Decks by Billie Thompson

Other Decks in Technology

Transcript

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

  2. Contents 1. Why are 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 »

    Humanising 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

  14. None
  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

  17. None
  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

  20. None
  21. OpenAPI Specification » Generate Clients: Yes, lots for PHP and

    other languages » Validate Standard: Yes » Documentation Generation: Yes, loads » Pleasant Editor: Yes, lots
  22. None
  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. What to take away

  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/