Symfony UK: API Contracts using Open API

Transcript

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

   View 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 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
   » Humanizing 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. 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 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