Sunshine PHP 2015 - Your API is Bad and You Should Feel Bad

Do you hate the Facebook API? We all do as well. So stop writing your API in their footsteps.

In this talk we will walk through how to construct a RESTful API, what makes an API your users/developers will love, and why you should eat your own dog food with API Driven Development.

Transcript

1. View Slide

2. Title
   Title
   Ben Edmunds
   Open Source
   Author
   PHP Town Hall Podcast
   CTO at Mindfulware
   Who is this guy?
   

   View Slide

3. Title
   Title
   Ben Edmunds
   @benedmunds
   http://benedmunds.com
   Who is this guy?
   

   View Slide

4. Title
   Title
   RESTful API Basics
   API Design
   Implementing your API
   Versioning, Auth, & Rate Limiting
   What Will We Cover?
   

   View Slide

5. Title
   Title
   RESTful API Basics
   

   View Slide

6. Title
   Title
   Representational State Transfer
   HTTP Methods
   GET, POST, PUT, DELETE
   Expressive
   Real-World Usage
   What is REST?
   

   View Slide

7. Title
   Title
   Formats
   JSON*
   XML
   Anything
   What is REST?
   

   View Slide

8. Title
   Title
   Most widely used data format is JSON
   Javascript Object Notation
   {
   key: ‘value’,
   anotherKey: ‘value2’
   }
   What is REST?
   

   View Slide

9. Title
   Title
   JSON usage in Javascript = familiar
   var object = {
   key: ‘value’,
   anotherKey: ‘value2’
   };
   What is REST?
   

   View Slide

10. Title
    Title
    Outputs
    {key: ‘value’}
    PHP
    echo json_encode(array(
    ‘key’ => ‘value’
    ));
    JSON encoding is supported natively
    in most languages
    What is REST?
    

    View Slide

11. Title
    Title
    Outputs
    array(
    ‘key’ => ‘value’
    )
    $json_data = “{key: ‘value’}”;
    print_r(json_decode($json_data));
    JSON decoding is just as simple
    PHP
    What is REST?
    

    View Slide

12. Warning
    This will be Opinionated
    

    View Slide

13. Title
    Title
    Simple
    Expressive
    Intuitive
    API Design
    

    View Slide

14. Title
    Title
    Simple
    Expressive
    Intuitive
    STABLE
    API Design
    

    View Slide

15. Title
    Title
    Simple
    Expressive
    Intuitive
    STABLE
    CONSISTENT
    API Design
    

    View Slide

16. Title
    Title
    Use the Facebook API
    DO THE OPPOSITE
    API Design
    

    View Slide

17. Title
    Title
    Document!
    Document!
    Document!
    API Design
    

    View Slide

18. Title
    Title
    To ADD or not to ADD
    API
    Driven
    Development
    API Design
    

    View Slide

19. Title
    Title
    HTTP Status Codes
    HTTP Status Cats
    to the Rescue!
    API Design
    

    View Slide

20. Title
    Title
    Status 2xx = Success
    API Design
    

    View Slide

21. Title
    Title
    Status 3xx = Redirect
    API Design
    

    View Slide

22. Title
    Title
    Status 4xx = Client Errors
    API Design
    

    View Slide

23. Title
    Title
    Status 5xx = Service Errors
    API Design
    

    View Slide

24. Title
    Title
    VERBS
    API Design
    

    View Slide

25. Title
    Title
    POST/PUT
    GET
    PUT
    DELETE
    HTTP Methods
    Create
    Read
    Update
    Delete
    =
    API Design
    

    View Slide

26. Title
    Title
    POST/PUT = Create
    api.domain.com/user
    PUT if all values are known
    API Design
    

    View Slide

27. Title
    Title
    GET = READ
    api.domain.com/user/2
    API Design
    

    View Slide

28. Title
    Title
    PUT = IDEMPOTENT
    Needs all identifying info
    Basically, include the ID
    API Design
    

    View Slide

29. Title
    Title
    Different Opinions
    PUT = create (idempotent)
    POST = create (unknown resource)
    PUT = update (resource is known)
    Put vs Post
    API Design
    

    View Slide

30. Title
    Title
    PUT = UPDATE
    api.domain.com/user/2
    {
    id: 2,
    first_name: ‘bob’,
    last_name: ‘cat’
    }
    API Design
    

    View Slide

31. Title
    Title
    DELETE = DELETE
    api.domain.com/user/2
    API Design
    

    View Slide

32. Title
    Title
    CONSISTENCY
    API Design
    

    View Slide

33. Title
    Title
    URL endpoints represent data
    /user = user
    /company = company
    API Design
    

    View Slide

34. Title
    Title
    A single Object maps to a singular URL
    api.domain.com/user/2
    api.domain.com/company/3
    API Design
    

    View Slide

35. Title
    Title
    Objects map to plural URLs
    api.domain.com/users
    api.domain.com/companies
    API Design
    

    View Slide

36. Title
    Title
    Common actions across most objects
    GET /user/2
    GET /company/3
    DELETE /user/2
    DELETE /company/3
    API Design
    

    View Slide

37. View Slide

38. Title
    Title
    https://site.com/api/statuses
    Maps to all of the statuses
    “Statuses” could be:
    SQL table
    NoSQL collection
    Aggregate Data
    API Design
    

    View Slide

39. Title
    Title
    https://site.com/api/status/1234
    Maps to a single status with
    the ID of 1234
    API Design
    

    View Slide

40. Title
    Title
    Creating
    If you know all of the data
    (including the ID)
    PUT https://site.com/api/status/1234
    API Design
    

    View Slide

41. Title
    Title
    Creating
    If you know all of the data
    (including the ID)
    PUT https://site.com/api/status/1234
    No matter how many times you send
    this data only one resource should
    ever be created
    Idempotent
    API Design
    

    View Slide

42. Title
    Title
    Creating
    If you know all of the data
    (including the ID)
    PUT https://site.com/api/status/1234
    {
    id: 1234,
    retweeted: false,
    active: true
    }
    API Design
    

    View Slide

43. Title
    Title
    Creating
    If you don’t know all of the data
    POST https://site.com/api/status
    Implementation
    

    View Slide

44. Title
    Title
    Creating
    Each time you post this data a new
    resource should be created
    Unique
    If you don’t know all of the data
    POST https://site.com/api/status
    Implementation
    

    View Slide

45. Title
    Title
    Creating
    If you don’t know all of the data
    POST https://site.com/api/status
    {user_id: 1,
    text: ‘Test Status’
    }
    Implementation
    

    View Slide

46. Title
    Title
    Creating
    If you don’t know all of the data
    POST https://site.com/api/status
    {user_id: 1,
    text: ‘Test Status’
    }
    Response
    {succes: true,
    id: 123
    }
    Implementation
    

    View Slide

47. Title
    Title
    Reading
    Get all statuses
    GET https://site.com/api/statuses
    API Design
    

    View Slide

48. Title
    Title
    Reading
    Complex requests that require
    additional data
    GET https://site.com/api/statuses
    API Design
    

    View Slide

49. Title
    Title
    Reading
    Get all of the statuses that have
    been retweeted and are active
    GET https://site.com/api/statuses ?
    retweeted=1&active=1
    API Design
    

    View Slide

50. Title
    Title
    Updating
    We know all of the identifying
    information so we PUT updates
    API Design
    

    View Slide

51. Title
    Title
    Updating
    We know all the data
    PUT https://site.com/api/status/123
    {id: 123,
    user_id: 1,
    text: ‘Test Status 2’
    }
    Implementation
    

    View Slide

52. Title
    Title
    Delete
    Just pass the identifying information
    {id: 123}
    DELETE https://site.com/api/status/123
    API Design
    

    View Slide

53. Title
    Title
    Relationships
    Get the user that posted a status
    GET https://site.com/api/status/1234/user
    API Design
    

    View Slide

54. View Slide

55. Title
    Title
    How to handle versioning?
    GET https://site.com/api/v1/statuses
    GET https://site.com/api/v2/statuses
    Each version has a separate route -
    Versioning
    

    View Slide

56. Title
    Title
    How to handle versioning?
    Route newest API through
    https://api.site.com
    GET https://site.com/api/v2/statuses
    GET https://site.com/api/statuses
    =
    Versioning
    

    View Slide

57. Title
    Title
    How to handle versioning?
    Accept Headers
    (HATEOAS)
    Versioning
    Accept: application vnd.github.user.v4+json
    

    View Slide

58. -OAS
    

    View Slide

59. Title
    Title
    Content Negotiation
    HATEOAS
    Hypermedia Controls
    

    View Slide

60. Title
    Title
    Content Negotiation
    Accept: application:x-yaml
    Accept: application:json
    Request “Accept” Header
    (JSON,XML,YAML, etc)
    Versioning
    

    View Slide

61. Title
    Title
    Content Negotiation
    Allow: GET, PUT, POST
    OPTIONS Http Request
    Versioning
    

    View Slide

62. Title
    Title
    Hypermedia Controls
    Links to Related Content
    Versioning
    { success: true,
    id: 123,
    links:
    {
    “rel”: ‘self’
    “url”: ‘/status/123’
    },
    {
    “rel”: ‘user’
    “url”: ‘/status/123/user’
    }
    }
    

    View Slide

63. Title
    Title
    Hypermedia Controls
    Links to Related Content
    Versioning
    { success: false,
    error: {
    “code”:‘errorFail’
    “message”: ‘You have Failed!’
    “url”: ‘http://domain.com/docs/errorFail’
    }
    }
    

    View Slide

64. View Slide

65. Title
    Title
    Who’s the Consumer?
    User Service
    Internal Service
    Authentication
    

    View Slide

66. Title
    Title
    Consumer = User
    OAuth
    Client Server
    Request Token ->
    <- Access Token
    Authentication
    

    View Slide

67. Title
    Title
    Consumer = User
    Standard
    Many Diff “Flows”
    Complicated Spec
    OAuth 2
    Authentication
    

    View Slide

68. Title
    Title
    Consumer = User
    Client Server
    Request ->
    w/AccessToken
    OAuth 2
    Authentication
    

    View Slide

69. Title
    Title
    Consumer = Internal
    Client Server
    Request ->
    w/AccessToken
    Access Token = Service Key+Client Key
    Authentication
    

    View Slide

70. Title
    Title
    Data Hash
    SHA1 ( $DATA )
    Authentication
    

    View Slide

71. View Slide

72. Title
    Title
    Prevent Abuse
    Maintain Availability
    Client Key
    IP Address
    User ID
    Rate Limiting
    

    View Slide

73. View Slide

74. Title
    Title
    How to debug as you
    develop?
    CURL
    Automated Tests
    Rested on OSX
    Debugging
    

    View Slide

75. Go Make
    Cool Things
    

    View Slide

76. Title
    Title
    https://leanpub.com/build-apis-you-wont-hate
    Book -
    Build APIs You Won’t Hate
    Tutorial -
    Demystifying REST
    https://tutsplus.com/tutorial/demystifying-rest/
    Resources
    

    View Slide

77. Title
    Title
    http://aaronparecki.com/articles/
    2012/07/29/1/oauth2-simplified
    Blog -
    OAuth 2 Simplified
    Book -
    OAuthello
    https://leanpub.com/oauthello-a-book-about-
    oauth/
    Resources
    

    View Slide

78. Title
    Title
    BuildSecurePHPapps.com
    Coupon Code:
    
    sunshine2015
    $3 off
    http://buildsecurephpapps.com/?coupon=sunshine2015
    Resources
    

    View Slide

79. Q/A TIME!
    https://joind.in/13438
    Ben Edmunds
    @benedmunds
    http://benedmunds.com
    http://buildsecurephpapps.com/?coupon=sunshine2015
    

    View Slide