Building APIs that delight (Part I)

D02b5e0b9a348fa8d9bd2cac025eead3?s=47 Steven Ringo
February 14, 2014

Building APIs that delight (Part I)

An overview of building APIs in Ruby, Rails and related. Looking at REST, API design, tooling, documentation and practices.

D02b5e0b9a348fa8d9bd2cac025eead3?s=128

Steven Ringo

February 14, 2014
Tweet

Transcript

  1. 1.

    Building APIs that delight (Part I) 11 February 2014 Rorosyd

    Steven Ringo | stevenringo | steven@stevenringo.com
  2. 4.
  3. 6.
  4. 7.
  5. 8.
  6. 11.

    A RESTifarian is a zealous proponent of the REST software

    architectural style as defined by Roy T. Fielding in Chapter 5 of his PhD. dissertation at UC Irvine. You can find RESTifarians in the wild on the REST-discuss mailing list. But be careful, RESTifarians can be extremely meticulous when discussing the finer points of REST.
  7. 12.

    A RESTifarian is a zealous proponent of the REST software

    architectural style as defined by Roy T. Fielding in Chapter 5 of his PhD. dissertation at UC Irvine. You can find RESTifarians in the wild on the REST-discuss mailing list. But be careful, RESTifarians can be extremely meticulous when discussing the finer points of REST.
  8. 14.

    Resource POST create GET read PUT / PATCH update* DELETE

    delete /dogs Create a new dog List dogs Bulk update dogs Delete all dogs /dogs/fido Show Fido Edit Fido Delete Fido
  9. 15.

    Keep URLs simple and intuitive Avoid verbs* Keep to two

    base URLs per resource. Keep verbs out of your base URLs Use HTTP verbs on collections and elements
  10. 18.
  11. 19.
  12. 27.

    { "invoices": [ { "invoiceId": "402892053e100406013e1024aaec00d7", "invoiceNumber": "INV00000091", "invoiceAmount": 801.73

    } ], "paymentId": "402892053e100406013e1024ab7c00e3", "amountCollected": 801.73, "success": true } Pay invoice/s
  13. 28.

    { "payment": { "id": "402892053e100406013e1024ab7c00e3", "amount_collected": 801.73 }, "invoices": [

    { "invoice": { "id": "402892053e100406013e1024aaec00d7", "number": "INV00000091", "amount": 801.73 } } ] } Pay invoice/s
  14. 29.

    { “invoice_payment": { "id": "402892053e100406013e1024ab7c00e3", "amount_collected": 801.73, "invoices": [ {

    "invoice": { "id": "402892053e100406013e1024aaec00d7", "number": "INV00000091", "amount": 801.73 } } ] } } Pay invoice/s
  15. 31.

    GET /convert?from=AUD&to=USD&amount=100 POST /convert { "convert": { "from": "AUD", "to":

    "USD", "amount": 100, "account": { "id": "184498321" } } }
  16. 32.
  17. 33.

    Everything worked: 200 OK ! You did something wrong: 400

    Bad Request ! We did something wrong: 500 Internal Server Error
  18. 35.