Upgrade to Pro — share decks privately, control downloads, hide ads and more …

[DevReach 2019] Never RESTing - RESTful API Bes...

[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.

Spencer Schneidenbach

October 22, 2019
Tweet

More Decks by Spencer Schneidenbach

Other Decks in Programming

Transcript

  1. Tue, 22 Oct | 11:30 AM – 12:20 PM Beta

    Room Spencer Schneidenbach
 RESTful API Best Practices Using ASP.NET Core
  2. 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
  3. 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
  4. Do what makes sense. Throw out the rest. Is that

    vague enough for you? @schneidenbach #NeverRest
  5. Designing your RESTful API I HAVE ONE RULE… okay I

    actually have TWO RULES @schneidenbach #NeverRest
  6. KISS Don’t be creative. Provide what is necessary – no

    more, no less. Use a handful of HTTP status codes. @schneidenbach #NeverRest
  7. 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
  8. KISS { "id": 1234, "active": true, "nameId": 345 } {

    "id": 345, "name": "Acme" } Customer API Name API GET /customers/1234 GET /names/345 @schneidenbach #NeverRest
  9. KISS That’s TWO REQUESTS per GET That’s TWO REQUESTS per

    POST What’s the point? @schneidenbach #NeverRest
  10. Don’t let your specific implementations leak if they are hard

    to use or understand. @schneidenbach #NeverRest
  11. KISS { "id": 1234, "active": true, "name": "Acme" } Customer

    API GET /customers/1234 @schneidenbach #NeverRest
  12. Second big rule – Be Consistent Be consistent with accepted

    best practices. Be consistent with yourself. @schneidenbach #NeverRest
  13. { "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
  14. 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
  15. 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
  16. Error reporting Errors are going to happen. How will you

    manage them? @schneidenbach #NeverRest
  17. 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."
  18. Error reporting Make finding and fixing errors as easy on

    your consumer as possible. @schneidenbach #NeverRest
  19. Use SSL. Don’t roll your own encryption. Pick an auth

    strategy that isn’t Basic. @schneidenbach #NeverRest Security
  20. Just remember to use all these things • MediatR •

    Fluent Validation • Autofac • Microsoft DI • Entity Framework • AutoMapper or…
  21. Documentation A good API lives and dies by its documentation.

    (you should tweet that out) @schneidenbach #NeverRest
  22. 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
  23. Maintaining your API Fix bugs and optimize. Don’t introduce breaking

    changes like removing properties. @schneidenbach #NeverRest