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

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.

4cae070608be3489262fe419c03498dc?s=128

Adrián Matellanes

October 08, 2016
Tweet

Transcript

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

    orgullosos
  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" }
  3. We’re building an API !

  4. We’re building a RESTful API !

  5. What is a RESTful API ?

  6. What is a RESTful API? Constraints • Client-Server • Stateless

    • Cacheable • Layered System • Uniform Interface
  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)
  8. RMM Richardson Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html

  9. RMM (Richardson Maturity Model) Level 1: Resources • GET -

    /api/characters • GET - /api/characters/583 • GET - /api/characters/211
  10. RMM (Richardson Maturity Model) Level 2: HTTP Verbs • GET

    • POST • DELETE • PUT • PATCH • OPTIONS • HEAD
  11. RMM (Richardson Maturity Model) Level 2: HTTP Verbs • POST

    - /api/characters • GET - /api/characters • GET|PUT|DELETE - /api/characters/823
  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", }
  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/
  14. HTTP Status Code

  15. HTTP Status Code 2xx Success • 200 - OK •

    201 - Created • 204 - No Content
  16. HTTP Status Code 3xx Redirection • 301 - Moved Permanently

    • 304 - Not Modified
  17. HTTP Status Code 4xx Client Error • 400 - Bad

    Request • 401 - Unauthorized • 403 - Forbidden • 404 - Not Found • 405 - Method Not Allowed
  18. HTTP Status Code 5xx Server Error • 500 - Internal

    Server Error • 501 - Not Implemented • 502 - Bad Gateway • 503 - Service Unavailable
  19. How to build a RESTful API?

  20. API

  21. Specification Development Testing Deployment

  22. Specification Testing Deployment Development

  23. Specification Deployment Development Testing

  24. Specification Development Testing Deployment

  25. API Specification

  26. API Specification Swagger 6,316 results 3,870 repositories 4,664 stars 528,000

    results http://swagger.io/specification/
  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' ...
  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' ...
  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
  30. API Specification RAML 506 results 834 repositories 2,329 stars 98,000

    results https://github.com/raml-org/raml-spec
  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 ...
  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
  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" } } }
  34. API Specification RAML # examples/character.json { "name": "Oberyn Martell" "gender":

    "Male" }
  35. API Specification API Blueprint 943 results 409 repositories 4,325 stars

    404,000 results https://github.com/apiaryio/api-blueprint
  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. ...
  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) ...
  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
  39. What should I choose?

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

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

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

  43. API Development

  44. What framework should I choose?

  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
  46. API Development What I DO NOT want • Object-Relational Manager

    (no DB connection) • Template engine
  47. API Development The Contenders

  48. Flask

  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
  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
  51. API Development Flask-RESTful Example from flask import Flask from flask_restful

    import Resource, Api app = Flask(__name__) api = Api(app) ...
  52. API Development Flask-RESTful Example ... class Character(Resource): def get(self, id):

    return { 'name': 'Oberyn Martell', 'culture': 'Dornish' } api.add_resource(Character, '/characters/<string:id>') ...
  53. API Development Flask-RESTful Example ... if __name__ == '__main__': app.run(debug=True)

  54. API Testing

  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

  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

  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'})
  58. Integration Testing Postman

  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
  60. Integration Testing Wiremock Mock your APIs for fast, robust and

    comprehensive testing https://github.com/tomakehurst/wiremock
  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" } } }
  62. CDC Consumer Driven Contracts http://martinfowler.com/articles/consumerDrivenContracts.html

  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

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

  65. API Deployment

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

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

  68. API Deployment Serverless

  69. API Developer Portal

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

  71. API Developer Portal Tips • Document precisely and with examples

    • Authentication • Endpoints • SDKs • Changelog
  72. More...

  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
  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/
  75. What’s missing....?

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

  77. Thank you! Questions?