Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

RESTful API Design Best Practices Using ASP.NET Web API

7,024 views

Published on

Designing and building RESTful APIs isn’t easy. On its surface, it may seem simple – after all, we’re only marshaling JSON back and forth over HTTP right? However, that’s only a small part of the equation. There are many things to keep in mind while building the systems that act as the key to your system.

In this session, we’ll delve into several best practices to keep in mind when designing your RESTful API. We’ll discuss authentication, versioning, controller/model design, and testability. We’ll also explore the do’s and don’t’s of RESTful API management so that you make sure your APIs are simple, consistent, and easy-to-use. Finally, we’ll discuss the importance of documentation and change management. The session will show examples using ASP.NET Web API and C#. However, this session will benefit anyone who is or might be working on a RESTful API.

Published in: Software
  • Be the first to comment

RESTful API Design Best Practices Using ASP.NET Web API

  1. 1. #NeverRest RESTful API Design Best Practices Using ASP.NET Web API Spencer Schneidenbach @schneidenbach
  2. 2. Slides, links, and more at rest.schneids.net @schneidenbach#NeverRest
  3. 3. Why? @schneidenbach#NeverRest
  4. 4. Developers have the power of choice @schneidenbach#NeverRest
  5. 5. Long-term benefits @schneidenbach#NeverRest Go from 0 to “make magic happen” Learn stuff and manage exceptions
  6. 6. Developers have the power of choice @schneidenbach#NeverRest
  7. 7. Developers have an opportunity create something better than the competition @schneidenbach#NeverRest
  8. 8. API Design is UX for Developers @schneidenbach#NeverRest
  9. 9. This quote sums it up nicely If you don’t make usability a priority, you’ll never have to worry about scalability. -Kirsten Hunter @synedra @schneidenbach#NeverRest
  10. 10. Some common themes @schneidenbach#NeverRest
  11. 11. @schneidenbach#NeverRest
  12. 12. Simple != Easy @schneidenbach#NeverRest
  13. 13. There’s No Silver Bullet @schneidenbach#NeverRest
  14. 14. What is REST? Representational State Transfer @schneidenbach#NeverRest
  15. 15. Uniform Interface Code on Demand (optional) Layered StatelessCacheableClient-Server The Six Constraints of REST @schneidenbach#NeverRest
  16. 16. Resource identification Uniform Interface constraint Content-Type: application/json Resource manipulation with representations Self-descriptive Hypermedia as the engine of application state (HATEOAS) GET /employees/1234 PUT /employees/1234 @schneidenbach#NeverRest
  17. 17. What is a RESTful API? RESTful API == an API that follows REST architecture Term has been sort of co-opted REST != JSON REST != HTTP Lots of people say “REST API” when they really mean HTTP JSON API @schneidenbach#NeverRest
  18. 18. Pragmatic REST RESTful API != Good API @schneidenbach#NeverRest
  19. 19. Do what makes sense. Throw out the rest. Is that vague enough for you? @schneidenbach#NeverRest
  20. 20. MaintainDocument ImplementDesign API Design Process @schneidenbach#NeverRest
  21. 21. Designing your RESTful API I HAVE ONE RULE… okay I actually have two rules @schneidenbach#NeverRest
  22. 22. (or, Keep it Simple, Stupid) @schneidenbach#NeverRest
  23. 23. KISS Don’t be creative. Provide what is necessary – no more, no less. Use a handful of HTTP status codes. @schneidenbach#NeverRest
  24. 24. 403 Forbidden (aka you can’t do that) 401 Unauthorized (aka not authenticated) 404 Not Found 400 Bad Request201 Created200 OK Good HTTP Codes @schneidenbach#NeverRest
  25. 25. KISS { "id": 1234, "active": true, "nameId": 345 } { "id": 345, "name": "Acme" } Customer API Name API GET /customers/1234 GET /names/345 @schneidenbach#NeverRest
  26. 26. KISS That’s TWO REQUESTS per GET That’s TWO REQUESTS per POST What’s the point? @schneidenbach#NeverRest
  27. 27. Don’t let your specific implementations leak if they are hard to use or understand. @schneidenbach#NeverRest
  28. 28. KISS { "id": 1234, "active": true, "name": "Acme" } Customer API GET /customers/1234 @schneidenbach#NeverRest
  29. 29. KISS Theory Annex Threshold Lilia @schneidenbach#NeverRest
  30. 30. KISS Inactive Deleted Visible Retired @schneidenbach#NeverRest
  31. 31. Second big rule – Be Consistent Be consistent with accepted best practices. Be consistent with yourself. @schneidenbach#NeverRest
  32. 32. PATCHDELETE POSTPUTGET Understanding verbs Remember consistency! @schneidenbach#NeverRest
  33. 33. Don’t mutate data with GETs. @schneidenbach#NeverRest
  34. 34. Resource identification Nouns vs. verbs Basically, use plural nouns @schneidenbach#NeverRest
  35. 35. { "invoices": [ { ... }, { ... } ] } GET /customers/1234/invoices GET /customers/1234 ?expand=invoices Within the parent object Sub-resource strategies As a separate request Using an expand parameter Be consistent, but be flexible when it makes sense @schneidenbach#NeverRest
  36. 36. GET considerations Sorting Filtering Paging @schneidenbach#NeverRest
  37. 37. Sorting/Ordering $orderBy=name desc $orderBy=name desc,hireDate @schneidenbach#NeverRest
  38. 38. Filtering $filter=(name eq 'Milk' or name eq 'Eggs') and price lt 2.55 @schneidenbach#NeverRest
  39. 39. Sorting and filtering for free Google “OData web api” @schneidenbach#NeverRest
  40. 40. Paging GET /customers? page=1 & pageSize=1000 { "pageNumber": 1, "results": [...], "nextPage": "/customers?page=2" } Good paging example on my blog: rest.schneids.net @schneidenbach#NeverRest
  41. 41. Do I need to sort/page/filter? Maybe! What do your consumers need? @schneidenbach#NeverRest
  42. 42. Versioning Your APIs should stand a test of time @schneidenbach#NeverRest
  43. 43. Versioning GET /customers Host: contoso.com Accept: application/json X-Api-Version: 1 @schneidenbach#NeverRest POST /customers Host: contoso.com Accept: application/json X-Api-Version: 2.0
  44. 44. Versioning Use URL versioning @schneidenbach#NeverRest GET /v1/customers Host: contoso.com Accept: application/json
  45. 45. Error reporting Errors are going to happen. How will you manage them? @schneidenbach#NeverRest
  46. 46. Error reporting { "name": "Arana Software" } @schneidenbach#NeverRest Requires name and state POST /vendors 400 Bad Request Content-Type: application/json "State is required." { "firstName": "Spencer" } Requires first and last name POST /employees 400 Bad Request Content-Type: application/json { "errorMessage": "Your request was invalid." }
  47. 47. Error reporting @schneidenbach#NeverRest
  48. 48. Error reporting Make finding and fixing errors as easy on your consumer as possible. @schneidenbach#NeverRest
  49. 49. AuthenticationEncryption Security @schneidenbach#NeverRest
  50. 50. Use SSL. Don’t roll your own encryption. Pick an auth strategy that isn’t Basic. @schneidenbach#NeverRest Security
  51. 51. Ok, time for some code examples and practical advise @schneidenbach#NeverRest
  52. 52. @schneidenbach#NeverRest Controller Anatomy
  53. 53. @schneidenbach#NeverRest
  54. 54. @schneidenbach#NeverRest
  55. 55. @schneidenbach#NeverRest
  56. 56. Use DTOs/per-request objects @schneidenbach#NeverRest
  57. 57. Separation of concerns @schneidenbach#NeverRest
  58. 58. @schneidenbach#NeverRest
  59. 59. @schneidenbach#NeverRest
  60. 60. Separation of concerns @schneidenbach#NeverRest Controllers should know “where,” not ”how.”
  61. 61. @schneidenbach#NeverRest
  62. 62. Validation @schneidenbach#NeverRest
  63. 63. Validation Validate. Validate. Validate. @schneidenbach#NeverRest Separate validation logic from object. Google Fluent Validation
  64. 64. Controller Good Architecture Request Handler/ServiceValidator Enforce separation of concerns for maintainability and testability. Google MediatR
  65. 65. Gotchas/ErrorsFormatting SchemaParametersEndpoints Documentation @schneidenbach#NeverRest
  66. 66. Documentation A good API lives and dies by its documentation. (you should tweet that out) @schneidenbach#NeverRest
  67. 67. Maintaining your API Vendor: “Hey, we’ve made some under-the-cover changes to our endpoint. It shouldn’t impact you, but let us know if it breaks something.” Us: ”Okay. Can you release it to test first so we can run our integration tests against the endpoint and make sure everything works?” Vendor: ”Well, actually we need it ASAP, so we’re releasing to prod in an hour.” @schneidenbach#NeverRest
  68. 68. Maintaining your API Fix bugs and optimize. Don’t introduce breaking changes like removing properties. @schneidenbach#NeverRest
  69. 69. Thank you! Slides, resources at rest.schneids.net schneids.net @schneidenbach

×