OSCON 2017 - Fake It Before You Make It: Mocking Your Way to Better HTTP APIs

OSCON 2017 - Fake It Before You Make It: Mocking Your Way to Better HTTP APIs

Ec6de98b75fa5831bc2f13564c5242fa?s=128

Dave Forgac

May 11, 2017
Tweet

Transcript

  1. Ian Zelikman ian.zelikman@gmail.com @izcoder Fake It Before You Make It:

    Mocking Your Way to Better HTTP APIs Dave Forgac dave@forgac.com @tylerdave
  2. Slides, Examples, & More: BetterAPIs.com

  3. Terminology

  4. REST

  5. REST Standard

  6. REST Standard Architectural Style

  7. REST Standard Architectural Style HTTP w/ Constraints

  8. REST Standard Architectural Style HTTP w/ Constraints REST-inspired HTTP APIs

  9. JSON

  10. JSON JavaScript Object Notation

  11. JSON JavaScript Object Notation { "things": [ "foo", "bar" ],

    "message": "Hello, World!" }
  12. JSON Schema

  13. JSON Schema { "title": "Example Schema", "type": "object", "properties": {

    "displayName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }
  14. YAML

  15. YAML Serialization format

  16. YAML Serialization format (More) human-readable

  17. YAML Serialization format (More) human-readable Superset of JSON

  18. YAML Serialization format (More) human-readable Superset of JSON Broad Support

  19. YAML Example --- talk: title: Fake It Before You Make

    It subtitle: Mocking Your Way to Better HTTP APIs topics: - apis - development bio: > A talk about defining API contracts before developing implementations. ...
  20. This Talk

  21. Requirement

  22. Requirement Accept POST

  23. Requirement Accept POST Return OK / validation errors

  24. Implementation

  25. Implementation Accept POST

  26. Implementation Accept POST Return OK / validation errors

  27. “That's not really what we wanted.”

  28. “That's not really what we wanted.”

  29. We provided { "valid": false, "errors": { "field_1": "too short"

    "field_2": "required", } } They expected { "valid": false, "errors": [ { "field": "field_1" "error": "too short", }, { "error": "required" "field": "field_2", } ] } The Difference *simplified example
  30. Can we do better?

  31. Can we do better?

  32. API Contract!

  33. API Contract

  34. API Contract Consumer ↔ Provider

  35. API Contract Consumer ↔ Provider Interface Specification

  36. API Contract Consumer ↔ Provider Interface Specification SLA, ToS, Limits,

    Pricing, etc.
  37. API Specification

  38. API Specification Machine Readable

  39. API Specification Machine Readable Requests / Responses

  40. API Specification Machine Readable Requests / Responses Basis of Contract

  41. Spec Formats

  42. Spec Formats WSDL

  43. Spec Formats WSDL WADL

  44. For REST(-like) APIs

  45. OpenAPI Spec (fka Swagger)

  46. OpenAPI Spec (fka Swagger) JSON or YAML

  47. OpenAPI Spec (fka Swagger) JSON or YAML OpenAPI Initiative

  48. Swagger / OpenAPI Spec 2.0 (1/3) 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/ host: api.betterapis.com basePath: / securityDefinitions: {} schemes: - http consumes: - application/json produces:
  49. Swagger / OpenAPI Spec 2.0 (2/3) paths: /foo: get: operationId:

    listFoo produces: - application/json parameters: - name: limit in: query required: false default: 10 type: integer format: int32 description: maximum number of foo to return responses: 200: description: List all foo schema: type: array
  50. Swagger / OpenAPI Spec 2.0 (3/3) definitions: Foo: title: Foo

    description: An example type of object type: object properties: name: type: string score: type: integer format: int32
  51. RAML

  52. RAML YAML Specification

  53. RAML YAML Specification Modeling

  54. RAML (1/3) #%RAML 1.0 title: Fake Better API version: 1.0.0

    baseUri: http://api.betterapis.com/ baseUriParamaters: {} documentation: - title: Fake Better API content: This is a basic example API for our talk at http://betterapis.com.
  55. RAML (2/3) types: Foo: displayName: Foo description: An example type

    of object type: object properties: name: required: false displayName: name type: string score: required: false displayName: score type: integer format: int32
  56. RAML (3/3) /foo: get: displayName: listFoo queryParameters: limit: required: false

    default: 10 displayName: limit description: maximum number of foo to return type: integer format: int32 responses: 200: description: List all foo body: application/json: displayName: response description: List all foo type: array
  57. API Blueprint

  58. API Blueprint Documentation as Specification

  59. API Blueprint Documentation as Specification MarkDown + Extensions

  60. API Blueprint (1/2) 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 (number, optional) - maximum number of foo to return + Default: 10 + Response 200 (application/json) List all foo
  61. API Blueprint (2/2) # Data Structures ## Foo (object) An

    example type of object ### Properties + `name` (string, optional) + `score` (number, optional)
  62. Comparison

  63. Comparison User-base

  64. Comparison User-base Tooling

  65. Comparison User-base Tooling Language Support

  66. Comparison User-base Tooling Language Support Recent Events

  67. Comparison User-base Tooling Language Support Recent Events It Depends...

  68. Defining Spec

  69. Defining Spec Implementation First

  70. Defining Spec Implementation First Contract First

  71. Defining Spec Implementation First Contract First Integrated

  72. Benefits

  73. Documentation

  74. Testing

  75. Code Generation

  76. Mocking

  77. Almost Demo Time!

  78. Almost Demo Time! Integrated Framework

  79. Almost Demo Time! Integrated Framework Connexion (Python)

  80. Almost Demo Time! Integrated Framework Connexion (Python) Spec as Config:

    Routing Validation Serialization
  81. Spec Write / Update Publish Mock Fake it ➡ Make

    it API Implement Validate
  82. Demo

  83. Tooling

  84. Tooling Frameworks

  85. Tooling Frameworks Mocking

  86. Tooling Frameworks Mocking Validation / Testing

  87. Resources BetterAPIs.com Further Reading

  88. Ian ian.zelikman@gmail.com @izcoder Thank You! Please leave feedback! "Rate This

    Session" on schedule listing Dave dave@forgac.com @tylerdave