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 full-size slide

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

    View full-size slide

  3. REST
    Standard

    View full-size slide

  4. REST
    Standard
    Architectural Style

    View full-size slide

  5. REST
    Standard
    Architectural Style
    HTTP w/ Constraints

    View full-size slide

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

    View full-size slide

  7. JSON
    JavaScript Object Notation

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  10. YAML
    Serialization format

    View full-size slide

  11. YAML
    Serialization format
    (More) human-readable

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  14. 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 full-size slide

  15. Requirement
    Accept POST

    View full-size slide

  16. Requirement
    Accept POST
    Return OK / validation errors

    View full-size slide

  17. Implementation

    View full-size slide

  18. Implementation
    Accept POST

    View full-size slide

  19. Implementation
    Accept POST
    Return OK / validation errors

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  22. 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 full-size slide

  23. Can we do better?

    View full-size slide

  24. Can we do better?

    View full-size slide

  25. API Contract!

    View full-size slide

  26. API Contract

    View full-size slide

  27. API Contract
    Consumer ↔ Provider

    View full-size slide

  28. API Contract
    Consumer ↔ Provider
    Interface Specification

    View full-size slide

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

    View full-size slide

  30. API Specification

    View full-size slide

  31. API Specification
    Machine Readable

    View full-size slide

  32. API Specification
    Machine Readable
    Requests / Responses

    View full-size slide

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

    View full-size slide

  34. Spec Formats

    View full-size slide

  35. Spec Formats
    WSDL

    View full-size slide

  36. Spec Formats
    WSDL
    WADL

    View full-size slide

  37. For REST(-like) APIs

    View full-size slide

  38. OpenAPI Spec
    (fka Swagger)

    View full-size slide

  39. OpenAPI Spec
    (fka Swagger)
    JSON or YAML

    View full-size slide

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

    View full-size slide

  41. 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 full-size slide

  42. 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 full-size slide

  43. 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 full-size slide

  44. RAML
    YAML Specification

    View full-size slide

  45. RAML
    YAML Specification
    Modeling

    View full-size slide

  46. 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 full-size slide

  47. 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 full-size slide

  48. 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 full-size slide

  49. API Blueprint

    View full-size slide

  50. API Blueprint
    Documentation as Specification

    View full-size slide

  51. API Blueprint
    Documentation as Specification
    MarkDown + Extensions

    View full-size slide

  52. 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 full-size slide

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

    View full-size slide

  54. Comparison
    User-base

    View full-size slide

  55. Comparison
    User-base
    Tooling

    View full-size slide

  56. Comparison
    User-base
    Tooling
    Language Support

    View full-size slide

  57. Comparison
    User-base
    Tooling
    Language Support
    Recent Events

    View full-size slide

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

    View full-size slide

  59. Defining Spec

    View full-size slide

  60. Defining Spec
    Implementation First

    View full-size slide

  61. Defining Spec
    Implementation First
    Contract First

    View full-size slide

  62. Defining Spec
    Implementation First
    Contract First
    Integrated

    View full-size slide

  63. Documentation

    View full-size slide

  64. Code Generation

    View full-size slide

  65. Almost Demo Time!

    View full-size slide

  66. Almost Demo Time!
    Integrated Framework

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  70. Tooling
    Frameworks

    View full-size slide

  71. Tooling
    Frameworks
    Mocking

    View full-size slide

  72. Tooling
    Frameworks
    Mocking
    Validation / Testing

    View full-size slide

  73. Resources
    BetterAPIs.com
    Further Reading

    View full-size slide

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

    View full-size slide