Cómo construir un API del que tus padres se sientan orgullosos

Necesitas construir una API, ¿pero conoces qué herramientas deberías usar? Cada día aparecen nuevas herramientas pensadas para crear, testear y desplegar APIs. En esta charla se presentará de manera resumida un caso real: el proceso de construcción de una API usando Python desde su diseño hasta su puesta en producción. Veremos los problemas encontrados por nuestro equipo y obviamente sus soluciones.

Transcript

1. Cómo construir
   un API
   del que tus padres
   se sientan orgullosos
   

   View Slide

2. About Me
   GET /speakers/adrian-matellanes
   {
   "name": "Adrián Matellanes",
   "roles": [
   "Lead API Developer",
   "Málaga Python Organizer"
   ],
   "worksAt": "Ebury"
   "twitter": "@_amatellanes",
   "github": "github.com/amatellanes"
   }
   

   View Slide

3. We’re building an API !
   

   View Slide

4. We’re building a
   RESTful API !
   

   View Slide

5. What is a
   RESTful API ?
   

   View Slide

6. What is a RESTful API?
   Constraints
   ● Client-Server
   ● Stateless
   ● Cacheable
   ● Layered System
   ● Uniform Interface
   

   View Slide

7. What is a RESTful API?
   Uniform Interface
   ● Identification of resources
   ● Manipulation of resources through representations
   ● Self Descriptive Messages
   ● Hypermedia As The Engine Of Application State (HATEOAS)
   

   View Slide

8. RMM
   Richardson
   Maturity
   Model
   http://martinfowler.com/articles/richardsonMaturityModel.html
   

   View Slide

9. RMM (Richardson Maturity Model)
   Level 1: Resources
   ● GET - /api/characters
   ● GET - /api/characters/583
   ● GET - /api/characters/211
   

   View Slide

10. RMM (Richardson Maturity Model)
    Level 2: HTTP Verbs
    ● GET
    ● POST
    ● DELETE
    ● PUT
    ● PATCH
    ● OPTIONS
    ● HEAD
    

    View Slide

11. RMM (Richardson Maturity Model)
    Level 2: HTTP Verbs
    ● POST - /api/characters
    ● GET - /api/characters
    ● GET|PUT|DELETE - /api/characters/823
    

    View Slide

12. RMM (Richardson Maturity Model)
    Level 3: Hypermedia controls
    GET /api/houses/362
    {
    "name": "House Stark of Winterfell",
    "region": "The North",
    "words": "Winter is Coming",
    "founder": "/api/characters/209",
    }
    

    View Slide

13. RMM (Richardson Maturity Model)
    Level 3: Hypermedia controls
    HAL
    http://stateless.co/hal_specification.html
    JSON-LD
    http://json-ld.org/
    Collection+JSON
    http://amundsen.com/media-types/collection/
    JSON Schema
    http://json-schema.org/
    

    View Slide

14. HTTP Status Code
    

    View Slide

15. HTTP Status Code
    2xx Success
    ● 200 - OK
    ● 201 - Created
    ● 204 - No Content
    

    View Slide

16. HTTP Status Code
    3xx Redirection
    ● 301 - Moved Permanently
    ● 304 - Not Modified
    

    View Slide

17. HTTP Status Code
    4xx Client Error
    ● 400 - Bad Request
    ● 401 - Unauthorized
    ● 403 - Forbidden
    ● 404 - Not Found
    ● 405 - Method Not Allowed
    

    View Slide

18. HTTP Status Code
    5xx Server Error
    ● 500 - Internal Server Error
    ● 501 - Not Implemented
    ● 502 - Bad Gateway
    ● 503 - Service Unavailable
    

    View Slide

19. How to build a RESTful API?
    

    View Slide

20. API
    

    View Slide

21. Specification
    Development
    Testing
    Deployment
    

    View Slide

22. Specification
    Testing
    Deployment
    Development
    

    View Slide

23. Specification
    Deployment
    Development
    Testing
    

    View Slide

24. Specification
    Development
    Testing
    Deployment
    

    View Slide

25. API Specification
    

    View Slide

26. API Specification
    Swagger
    6,316 results
    3,870 repositories
    4,664 stars
    528,000 results
    http://swagger.io/specification/
    

    View Slide

27. API Specification
    Swagger
    swagger: '2.0'
    info:
    version: '1.0.0'
    title: Game of Thrones API
    Description: All the data from the universe of Ice And Fire you've ever wanted
    schemes:
    - https
    basePath: /v1
    produces:
    - application/json
    securityDefinitions:
    OauthSecurity:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    ...
    

    View Slide

28. API Specification
    Swagger
    …
    paths:
    /characters/{id}:
    get:
    summary: Get specific character
    parameters:
    - name: id
    in: path
    description: The identifier of this character
    required: true
    type: string
    responses:
    200:
    description: History information for the given character
    schema:
    $ref: '#/definitions/Character'
    ...
    

    View Slide

29. API Specification
    Swagger
    …
    definitions:
    Character:
    type: object
    properties:
    name:
    type: string
    description: The name of this character
    gender:
    type: string
    description: The gender of this character
    example:
    name: Oberyn Martell
    gender: Male
    

    View Slide

30. API Specification
    RAML
    506 results
    834 repositories
    2,329 stars
    98,000 results
    https://github.com/raml-org/raml-spec
    

    View Slide

31. API Specification
    RAML
    #%RAML 1.0
    title: Game of Thrones API
    version: v1
    baseUri: http://{hostName}.com
    baseUriParameters:
    hostName:
    description: The name of the host
    mediaType: application/json
    documentation:
    - title: Game of Thrones API Documentation
    content: All the data from the universe of Ice And Fire you've ever wanted
    securitySchemes:
    oauth_2_0: !include securitySchemes/oauth_2_0.raml
    ...
    

    View Slide

32. API Specification
    RAML
    …
    /characters:
    /{id}:
    uriParameters:
    id:
    type: number
    description: The identifier of this character
    get:
    description: |
    Get specific character
    responses:
    200:
    body:
    application/json:
    schema: !include schemas/character.json
    example: !include examples/character.json
    

    View Slide

33. API Specification
    RAML
    # schemas/character.json
    {
    "type": "object",
    "$schema": "http://json-schema.org/draft-03/schema",
    "required": true,
    "properties": {
    "name": {
    "type": "string",
    "required": true,
    "maxLength": 125
    },
    "gender": {
    "type": "string"
    }
    }
    }
    

    View Slide

34. API Specification
    RAML
    # examples/character.json
    {
    "name": "Oberyn Martell"
    "gender": "Male"
    }
    

    View Slide

35. API Specification
    API Blueprint
    943 results
    409 repositories
    4,325 stars
    404,000 results
    https://github.com/apiaryio/api-blueprint
    

    View Slide

36. API Specification
    API Blueprint
    FORMAT: 1A
    HOST: http://got.api.com/
    # Game of Thrones API
    All the data from the universe of Ice And Fire you've ever wanted.
    ...
    

    View Slide

37. API Specification
    API Blueprint
    ...
    # Group Characters
    ## Character Resource [/characters/{id}]
    + Parameters
    + id: 422 (number) - The identifier of this character
    ### Get specific character [GET]
    + Response 200 (application/json)
    + Attributes
    - characters (Character)
    ...
    

    View Slide

38. API Specification
    API Blueprint
    ...
    # Data Structures
    ## Character (object)
    - name: Oberyn Martell (required, string) - The name of this character
    - gender: Male (required, string) - The gender of this character
    

    View Slide

39. What should I choose?
    

    View Slide

40. API Specification
    The API Transformer: Convertron
    https://apimatic.io/transformer
    

    View Slide

41. API Specification
    API Documentation Generator
    https://github.com/lord/slate
    

    View Slide

42. API Specification
    API Documentation Generator
    https://apiary.io/
    

    View Slide

43. API Development
    

    View Slide

44. What framework should I choose?
    

    View Slide

45. API Development
    What I DO want
    ● Python 3 Support
    ● HTTP request/response
    ● Easy to understand and use (documentation, minimal magic, no surprise)
    ● Packages
    ● URL Routing (RESTful)
    ● WSGI
    

    View Slide

46. API Development
    What I DO NOT want
    ● Object-Relational Manager (no DB connection)
    ● Template engine
    

    View Slide

47. API Development
    The Contenders
    

    View Slide

48. Flask
    

    View Slide

49. API Development
    Awesome Python
    webargs - Parse HTTP request arguments
    https://github.com/sloria/webargs
    marshmallow - Simplified object serialization
    https://github.com/marshmallow-code/marshmallow
    Requests - HTTP for Humans
    https://github.com/kennethreitz/requests
    

    View Slide

50. API Development
    Awesome Flask
    Flask-RESTful - Quick building REST APIs
    https://github.com/flask-restful/flask-restful
    Flask API - Browsable Web API
    https://github.com/tomchristie/flask-api
    Connexion - Automagically handles HTTP requests based on Swagger Spec
    https://github.com/zalando/connexion
    

    View Slide

51. API Development
    Flask-RESTful Example
    from flask import Flask
    from flask_restful import Resource, Api
    app = Flask(__name__)
    api = Api(app)
    ...
    

    View Slide

52. API Development
    Flask-RESTful Example
    ...
    class Character(Resource):
    def get(self, id):
    return {
    'name': 'Oberyn Martell',
    'culture': 'Dornish'
    }
    api.add_resource(Character, '/characters/')
    ...
    

    View Slide

53. API Development
    Flask-RESTful Example
    ...
    if __name__ == '__main__':
    app.run(debug=True)
    

    View Slide

54. API Testing
    

    View Slide

55. API Testing
    Unit Testing
    unittest
    https://docs.python.org/3/library/unittest.html
    pytest
    https://github.com/pytest-dev/pytest
    nose
    https://github.com/nose-devs/nose
    

    View Slide

56. API Testing
    Mocking Requests
    HTTPretty
    https://github.com/gabrielfalcao/HTTPretty
    httmock
    https://github.com/patrys/httmock
    mock
    https://docs.python.org/3/library/unittest.mock.html
    

    View Slide

57. API Testing
    HTTPretty Example
    @httpretty.activate
    def test_got_api_returning_deals():
    httpretty.register_uri(httpretty.GET,
    'http://api.got.com/v1/characters/583',
    body='{'name': 'Jon Snow'}',
    content_type='application/json')
    response = requests.get('http://api.got.com/v1/characters/583')
    expect(response.json()).to.equal({'name': 'Jon Snow'})
    

    View Slide

58. Integration Testing
    Postman
    

    View Slide

59. Integration Testing
    Dredd
    A language-agnostic command-line tool for validating API
    description document against backend implementation of the
    API.
    https://github.com/apiaryio/dredd
    

    View Slide

60. Integration Testing
    Wiremock
    Mock your APIs for fast, robust and comprehensive testing
    https://github.com/tomakehurst/wiremock
    

    View Slide

61. Integration Testing
    Wiremock stub example
    {
    "request": {
    "method": "GET",
    "url": "/v1/characters/583"
    },
    "response": {
    "status": 200,
    "bodyFileName": "jon-snow.json",
    "headers": {
    "Content-Type": "application/json"
    }
    }
    }
    

    View Slide

62. CDC
    Consumer Driven Contracts
    http://martinfowler.com/articles/consumerDrivenContracts.html
    

    View Slide

63. API Testing
    Performance Testing
    ab
    https://httpd.apache.org/docs/2.4/programs/ab.html
    Locust
    https://github.com/locustio/locust
    wrk
    https://github.com/wg/wrk
    

    View Slide

64. API Testing
    Security Testing
    Secure Pro
    https://smartbear.com/product/ready-api/secure/overview/
    

    View Slide

65. API Deployment
    

    View Slide

66. API Deployment
    API Gateway
    http://microservices.io/patterns/apigateway.html
    

    View Slide

67. API Deployment
    API Gateway
    Amazon API Gateway
    https://aws.amazon.com/api-gateway/
    Kong
    https://getkong.org/
    

    View Slide

68. API Deployment
    Serverless
    

    View Slide

69. API Developer Portal
    

    View Slide

70. Your API is not for machine, is for people
    

    View Slide

71. API Developer Portal
    Tips
    ● Document precisely and with examples
    ● Authentication
    ● Endpoints
    ● SDKs
    ● Changelog
    

    View Slide

72. More...
    

    View Slide

73. More...
    API Design Guides
    PayPal API Style Guide
    https://github.com/paypal/api-standards
    Heroku Platform HTTP API Design Guide
    https://github.com/interagent/http-api-design
    Microsoft REST API Guidelines
    https://github.com/Microsoft/api-guidelines
    

    View Slide

74. More...
    API Examples
    GitHub API v3
    https://developer.github.com/v3/
    Facebook Graph API
    https://developers.facebook.com/docs/graph-api
    Twitter REST API
    https://dev.twitter.com/rest/public
    Spotify Web API
    https://developer.spotify.com/web-api/
    

    View Slide

75. What’s missing....?
    

    View Slide

76. What’s missing....?
    :(
    ● Versioning
    ● Authentication
    ● GraphQL
    

    View Slide

77. Thank you!
    Questions?
    

    View Slide