PyOhio 2016 - Fake It Before You Make It: Mocking Your Way to Better HTTP APIs

http://betterapis.com/

Transcript

1. Fake It Before You Make It Mocking Your Way to Better HTTP APIs
2. Slides, Notes, Examples http://BetterAPIs.com/
3. Terminology
4. REST Standard Architectural Style Constraints REST-like HTTP APIs
5. API Contract Client ↔ Provider Interface Specification SLA, ToS, Limits, Pricing, etc.
6. JSON JavaScript Object Notation { "things": [ "foo", "bar" ], "message": "Hello, World!" }
7. JSON Schema { "title": "Example Schema", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }
8. YAML Serialization format (More) human-readable Subset of JSON Borad Language Support
9. This Talk
10. Requirement Accept POST Return OK / validation errors
11. Implementation Accept POST Return OK / validation errors
12. “That's not really what we wanted.” ಠ_ಠ
13. The Difference We provided They expected * simplified example { "valid": false, "errors": { "field_1": "too short" "field_2": "required", } } { "valid": false, "errors": [ { "field": "field_1" "error": "too short", }, { "error": "required" "field": "field_2", } ] }
14. How can we do better?
15. API Specification Machine Readable Basis of “Contract”
16. History WSDL, WADL
17. For REST(ish) APIs
18. Swagger ➡️ OpenAPI JSON Specification Rich Ecosystem 2.0: YAML ➡️ JSON OpenAPI Initiative
19. Swagger Example swagger: '2.0' info: version: '1.0.0' title: Fake Better API description: > This is a basic example API for our talk at http://betterapis.com. termsOfService: http://betterapis.com/terms/ contact: name: API Team email: apiteam@betterapis.com url: http://betterapis.com/contact/ license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html host: api.betterapis.com basePath: / securityDefinitions: {} schemes: - http consumes: - application/json produces: ...
20. Swagger Example Contd. paths: /foo: get: operationId: listFoo produces: - application/json parameters: - name: limit in: query type: integer description: maximum number of foo to return responses: 200: description: List all foo schema: type: array items: $ref: '#/definitions/Foo' ... definitions: Foo: title: Foo description: An example type of object type: object properties:
21. RAML YAML Specification Modeling Inheritance 1.0 Just Released RAML Workgroup
22. RAML Example #%RAML 0.8 title: Fake Better API version: 1.0.0 documentation: - title: Fake Better API content: Basic example API for our talk at http://betterapis.com. baseUri: http://api.betterapis.com/ schemas: - Foo-array: | { "type": "array", "items": { "id": "Foo", "title": "Foo", "description": "An example type of object", "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "integer", "format": "int32" } ...
23. RAML Example Contd. /foo: /{fooId}: uriParameters: fooId: description: ID of the foo type: string required: true displayName: fooId get: displayName: getFooByID responses: 200: description: Foo with the specified ID 404: description: Foo with specified ID not found get: displayName: listFoo responses: 200: description: List all foo body: application/json: schema: Foo-array ... `
24. API Blueprint Documentation as Specification MarkDown + Extensions Node & .Net Open RFC Process
25. API Blueprint Example FORMAT: 1A HOST: http://api.betterapis.com/ # Fake Better API This is a basic example API for our talk at http://betterapis.com. # Foo [/foo{?limit}] ## listFoo [GET] + Parameters + limit (, optional) - maximum number of foo to return + Default: 10 + Response 200 (application/json) List all foo + Attributes (array[Foo]) ...
26. API Blueprint Example Contd. # Foo [/foo] ## putFoo [PUT] + Request (application/json) + Attributes (Foo) + Response 200 (application/json) Updates a foo + Attributes (Dynamic) + Response 400 Invalid foo data ## postFoo [POST] + Request (application/json) + Attributes (Foo) + Response 200 (application/json) ...
27. Comparison User-base Tooling Language It Depends...
28. “How do we create the specification?”
29. “We have a specification; now what?”
30. Documentation
31. Mocking
32. Testing
33. Code Generation
34. Contract-first Then implement
35. Spec Build / Update Publish Mock Fake it ➡️ Make it API Implement Validate
36. Demo
37. Python-specific API Blueprint plueprint Swagger / OpenAPI Multiple parsers Connexion RAML ramlfications griffin (alpha) RAMSES
38. Resources http://BetterAPIs.com/ Further Reading
39. Thank You! Ian ian.zelikman@gmail.com @izcoder Slides, notes, & examples: Questions? Dave dave@forgac.com @tylerdave http://BetterAPIs.com/