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

More Decks by Dave Forgac

Other Decks in Technology

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/