[DevReach 2019] Never RESTing - RESTful API Best Practices using ASP.NET Core Web API

Designing and building RESTful APIs isn’t easy. On its surface, it may seem simple – after all, developers are only marshaling JSON back and forth over HTTP, right? Believe it or not, 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. Attendees will learn about authentication, versioning, controller/model design, testability, documentation and change management. This session will 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.

Examples will be done using ASP.NET Core Web API and C#. However, this session will benefit anyone who is or might be working on a RESTful API.

Transcript

1. Tue, 22 Oct | 11:30 AM – 12:20 PM Beta Room Spencer Schneidenbach
 RESTful API Best Practices Using ASP.NET Core
2. Slides, links, and more at rest.schneids.net @schneidenbach #NeverRest
3. Why? @schneidenbach #NeverRest
4. @schneidenbach #NeverRest
5. @schneidenbach #NeverRest
6. API Design is UX for Developers @schneidenbach #NeverRest
7. Some common themes @schneidenbach #NeverRest
8. @schneidenbach #NeverRest
9. Simple != Easy @schneidenbach #NeverRest
10. There’s No Silver Bullet @schneidenbach #NeverRest
11. What is REST? Representational State Transfer @schneidenbach #NeverRest
12. Uniform Interface Code on Demand (optional) Layered Stateless Cacheable Client-Server The Six Constraints of REST @schneidenbach #NeverRest
13. 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
14. 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
15. Pragmatic REST RESTful API != Good API @schneidenbach #NeverRest
16. Do what makes sense. Throw out the rest. Is that vague enough for you? @schneidenbach #NeverRest
17. Maintain Document Implement Design API Design Process @schneidenbach #NeverRest
18. Designing your RESTful API I HAVE ONE RULE… okay I actually have TWO RULES @schneidenbach #NeverRest
19. KISS (or, Keep it Simple, Stupid) @schneidenbach #NeverRest
20. KISS Don’t be creative. Provide what is necessary – no more, no less. Use a handful of HTTP status codes. @schneidenbach #NeverRest
21. 403 Forbidden (aka you can’t do that) 401 Unauthorized (aka not authenticated) 404 Not Found 400 Bad Request 201 Created 200 OK Good HTTP Codes @schneidenbach #NeverRest
22. KISS { "id": 1234, "active": true, "nameId": 345 } { "id": 345, "name": "Acme" } Customer API Name API GET /customers/1234 GET /names/345 @schneidenbach #NeverRest
23. KISS That’s TWO REQUESTS per GET That’s TWO REQUESTS per POST What’s the point? @schneidenbach #NeverRest
24. Don’t let your specific implementations leak if they are hard to use or understand. @schneidenbach #NeverRest
25. KISS { "id": 1234, "active": true, "name": "Acme" } Customer API GET /customers/1234 @schneidenbach #NeverRest
26. KISS Inactive Deleted Visible Retired @schneidenbach #NeverRest
27. @schneidenbach #NeverRest
28. @schneidenbach #NeverRest
29. Second big rule – Be Consistent Be consistent with accepted best practices. Be consistent with yourself. @schneidenbach #NeverRest
30. PATCH DELETE POST PUT GET Understanding verbs Remember consistency! @schneidenbach #NeverRest
31. Don’t mutate data with GETs. @schneidenbach #NeverRest
32. Resource identification Nouns vs. verbs Basically, use plural nouns @schneidenbach #NeverRest
33. { "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
34. GET considerations Sorting Filtering Paging @schneidenbach #NeverRest
35. Sorting/Filtering GET /customers?name=Spencer @schneidenbach #NeverRest
36. Paging GET /customers? page=1 & pageSize=1000 { "pageNumber": 1, "results": [...], "nextPage": "/customers?page=2" } @schneidenbach #NeverRest Good paging example on my website: rest.schneids.net
37. Do I need to sort/page/filter? Maybe! What do your consumers need? @schneidenbach #NeverRest
38. Versioning Your APIs should stand a test of time @schneidenbach #NeverRest
39. 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
40. Versioning Use URL versioning @schneidenbach #NeverRest GET /v1/customers Host: contoso.com Accept: application/json
41. Error reporting Errors are going to happen. How will you manage them? @schneidenbach #NeverRest
42. Error reporting { "name": "Aviron Software" } @schneidenbach #NeverRest { "firstName": "Spencer" } Requires first and last name POST /employees 400 Bad Request Content-Type: application/json { "errorMessage": "Your request was invalid." } Requires name and state POST /vendors 400 Bad Request Content-Type: application/json "State is required."
43. Error reporting @schneidenbach #NeverRest
44. Error reporting Make finding and fixing errors as easy on your consumer as possible. @schneidenbach #NeverRest
45. Authentication Encryption Security @schneidenbach #NeverRest
46. Use SSL. Don’t roll your own encryption. Pick an auth strategy that isn’t Basic. @schneidenbach #NeverRest Security
47. Ok, time for some code examples and practical advise @schneidenbach #NeverRest
48. Typical controller @schneidenbach #NeverRest
49. @schneidenbach #NeverRest
50. @schneidenbach #NeverRest
51. @schneidenbach #NeverRest
52. Separation of concerns @schneidenbach #NeverRest Controllers should know “where,” not ”how.” Enter MediatR
55. @schneidenbach #NeverRest
56. Validation Validate. Validate. Validate. @schneidenbach #NeverRest Separate validation logic from object. Google Fluent Validation
59. Controller Good Architecture Request Handler/Service Validator Enforce separation of concerns for maintainability and testability.
60. Just remember to use all these things • MediatR • Fluent Validation • Autofac • Microsoft DI • Entity Framework • AutoMapper or…
61. rest.schneids.net
63. Gotchas/Errors Formatting Schema Parameters Endpoints Documentation @schneidenbach #NeverRest
64. Documentation A good API lives and dies by its documentation. (you should tweet that out) @schneidenbach #NeverRest
65. 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
66. @schneidenbach #NeverRest
67. Maintaining your API Fix bugs and optimize. Don’t introduce breaking changes like removing properties. @schneidenbach #NeverRest
68. Thank you! Slides, resources at rest.schneids.net schneids.net @schneidenbach
69. Session Feedback
 Your Time & Opinion is Valued
 https://www.telerik.com/devreach/day1feedback