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. API Contracts using
    Open API
    Billie Thompson
    @PurpleBooth
    https://github.com/PurpleBooth/book-store

    View full-size slide

  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

    View full-size slide

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

    View full-size slide

  4. Conway's Law

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  7. Changing
    communication
    between stakeholders

    View full-size slide

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

    View full-size slide

  9. The Why!
    » Learn about requirements
    » Share Expectations
    » Humanizing teams creates respect
    » Living Documentation

    View full-size slide

  10. A Contract
    Options for defining one

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  13. 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.

    View full-size slide

  14. API Blueprint

    View full-size slide

  15. 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

    View full-size slide

  16. OpenAPI Specification

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  19. 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)

    View full-size slide

  20. How to write Open API
    Specifications

    View full-size slide

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

    View full-size slide

  22. {
    "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"
    ],

    View full-size slide

  23. {"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"
    }
    }
    }
    }
    }
    }
    },

    View full-size slide

  24. {"definitions": {
    "Pet": {
    "type": "object",
    "required": [
    "id",
    "name"
    ],
    "properties": {
    "id": {
    "type": "integer",
    "format": "int64"
    },
    "name": {
    "type": "string"
    },
    "tag": {
    "type": "string"
    }
    }
    }
    }

    View full-size slide

  25. A Practical Example
    Mandatory Symfony Example

    View full-size slide

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

    View full-size slide

  27. The tooling rocks!

    View full-size slide

  28. 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)

    View full-size slide

  29. 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/

    View full-size slide