Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

Ec6de98b75fa5831bc2f13564c5242fa?s=128

Dave Forgac

July 31, 2016
Tweet

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/