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

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/