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

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

Dave Forgac

May 11, 2017
Tweet

More Decks by Dave Forgac

Other Decks in Technology

Transcript

  1. Ian Zelikman
    [email protected]
    @izcoder
    Fake It Before
    You Make It:
    Mocking Your Way to
    Better HTTP APIs
    Dave Forgac
    [email protected]
    @tylerdave

    View Slide

  2. Slides, Examples, & More:
    BetterAPIs.com

    View Slide

  3. Terminology

    View Slide

  4. REST

    View Slide

  5. REST
    Standard

    View Slide

  6. REST
    Standard
    Architectural Style

    View Slide

  7. REST
    Standard
    Architectural Style
    HTTP w/ Constraints

    View Slide

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

    View Slide

  9. JSON

    View Slide

  10. JSON
    JavaScript Object Notation

    View Slide

  11. JSON
    JavaScript Object Notation
    {
    "things": [
    "foo",
    "bar"
    ],
    "message": "Hello, World!"
    }

    View Slide

  12. JSON Schema

    View Slide

  13. JSON Schema
    {
    "title": "Example Schema",
    "type": "object",
    "properties": {
    "displayName": {
    "type": "string"
    },
    "age": {
    "description": "Age in years",
    "type": "integer",
    "minimum": 0
    }
    },
    "required": ["firstName", "lastName"]
    }

    View Slide

  14. YAML

    View Slide

  15. YAML
    Serialization format

    View Slide

  16. YAML
    Serialization format
    (More) human-readable

    View Slide

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

    View Slide

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

    View Slide

  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.
    ...

    View Slide

  20. This Talk

    View Slide

  21. Requirement

    View Slide

  22. Requirement
    Accept POST

    View Slide

  23. Requirement
    Accept POST
    Return OK / validation errors

    View Slide

  24. Implementation

    View Slide

  25. Implementation
    Accept POST

    View Slide

  26. Implementation
    Accept POST
    Return OK / validation errors

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

  30. Can we do better?

    View Slide

  31. Can we do better?

    View Slide

  32. API Contract!

    View Slide

  33. API Contract

    View Slide

  34. API Contract
    Consumer ↔ Provider

    View Slide

  35. API Contract
    Consumer ↔ Provider
    Interface Specification

    View Slide

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

    View Slide

  37. API Specification

    View Slide

  38. API Specification
    Machine Readable

    View Slide

  39. API Specification
    Machine Readable
    Requests / Responses

    View Slide

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

    View Slide

  41. Spec Formats

    View Slide

  42. Spec Formats
    WSDL

    View Slide

  43. Spec Formats
    WSDL
    WADL

    View Slide

  44. For REST(-like) APIs

    View Slide

  45. OpenAPI Spec
    (fka Swagger)

    View Slide

  46. OpenAPI Spec
    (fka Swagger)
    JSON or YAML

    View Slide

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

    View Slide

  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: [email protected]
    url: http://betterapis.com/contact/
    host: api.betterapis.com
    basePath: /
    securityDefinitions: {}
    schemes:
    - http
    consumes:
    - application/json
    produces:

    View Slide

  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

    View Slide

  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

    View Slide

  51. RAML

    View Slide

  52. RAML
    YAML Specification

    View Slide

  53. RAML
    YAML Specification
    Modeling

    View Slide

  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.

    View Slide

  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

    View Slide

  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

    View Slide

  57. API Blueprint

    View Slide

  58. API Blueprint
    Documentation as Specification

    View Slide

  59. API Blueprint
    Documentation as Specification
    MarkDown + Extensions

    View Slide

  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

    View Slide

  61. API Blueprint (2/2)
    # Data Structures
    ## Foo (object)
    An example type of object
    ### Properties
    + `name` (string, optional)
    + `score` (number, optional)

    View Slide

  62. Comparison

    View Slide

  63. Comparison
    User-base

    View Slide

  64. Comparison
    User-base
    Tooling

    View Slide

  65. Comparison
    User-base
    Tooling
    Language Support

    View Slide

  66. Comparison
    User-base
    Tooling
    Language Support
    Recent Events

    View Slide

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

    View Slide

  68. Defining Spec

    View Slide

  69. Defining Spec
    Implementation First

    View Slide

  70. Defining Spec
    Implementation First
    Contract First

    View Slide

  71. Defining Spec
    Implementation First
    Contract First
    Integrated

    View Slide

  72. Benefits

    View Slide

  73. Documentation

    View Slide

  74. Testing

    View Slide

  75. Code Generation

    View Slide

  76. Mocking

    View Slide

  77. Almost Demo Time!

    View Slide

  78. Almost Demo Time!
    Integrated Framework

    View Slide

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

    View Slide

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

    View Slide

  81. Spec
    Write / Update
    Publish
    Mock
    Fake it ➡ Make it
    API
    Implement
    Validate

    View Slide

  82. Demo

    View Slide

  83. Tooling

    View Slide

  84. Tooling
    Frameworks

    View Slide

  85. Tooling
    Frameworks
    Mocking

    View Slide

  86. Tooling
    Frameworks
    Mocking
    Validation / Testing

    View Slide

  87. Resources
    BetterAPIs.com
    Further Reading

    View Slide

  88. Ian
    [email protected]
    @izcoder
    Thank You!
    Please leave feedback!
    "Rate This Session" on schedule listing
    Dave
    [email protected]
    @tylerdave

    View Slide