$30 off During Our Annual Pro Sale. View Details »

PHP London: API Contracts using Open API

PHP London: API Contracts using Open API

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

    View Slide

  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

    View Slide

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

    View Slide

  4. Conway's Law

    View Slide

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

    View Slide

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

    View Slide

  7. Changing
    communication
    between stakeholders

    View Slide

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

    View Slide

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

    View Slide

  10. A Contract
    Options for defining one

    View Slide

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

    View Slide

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

    View Slide

  13. RAML

    View Slide

  14. View Slide

  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.

    View Slide

  16. API Blueprint

    View Slide

  17. View Slide

  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

    View Slide

  19. OpenAPI Specification

    View Slide

  20. View Slide

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

    View Slide

  22. View Slide

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

    View Slide

  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)

    View Slide

  25. How to write Open API
    Specifications

    View Slide

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

    View Slide

  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"
    ],

    View Slide

  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"
    }
    }
    }
    }
    }
    }
    },

    View Slide

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

    View Slide

  30. A Practical Example
    Mandatory Symfony Example

    View Slide

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

    View Slide

  32. The tooling rocks!

    View Slide

  33. What to take away

    View Slide

  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/

    View Slide