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.
#NeverRest
RESTful API Design Best Practices
Using ASP.NET Web API
Spencer Schneidenbach
@schneidenbach
Slides, links, and more at
rest.schneids.net
@schneidenbach#NeverRest
Why?
@schneidenbach#NeverRest
Developers have the power of choice
@schneidenbach#NeverRest
Long-term benefits
@schneidenbach#NeverRest
Go from 0 to “make magic happen”
Learn stuff and manage exceptions
Developers have the power of choice
@schneidenbach#NeverRest
Developers have an opportunity create
something better than the competition
@schneidenbach#NeverRest
API Design is UX for Developers
@schneidenbach#NeverRest
This quote sums it up nicely
If you don’t make usability a priority, you’ll never
have to worry about scalability.
-Kirste...
Some common themes
@schneidenbach#NeverRest
@schneidenbach#NeverRest
Simple != Easy
@schneidenbach#NeverRest
There’s No Silver Bullet
@schneidenbach#NeverRest
What is REST?
Representational State Transfer
@schneidenbach#NeverRest
Uniform Interface
Code on Demand
(optional)
Layered
StatelessCacheableClient-Server
The Six Constraints of REST
@schneiden...
Resource
identification
Uniform Interface constraint
Content-Type:
application/json
Resource
manipulation with
representat...
What is a RESTful API?
RESTful API == an API that follows REST architecture
Term has been sort of co-opted
REST != JSON
RE...
Pragmatic REST
RESTful API != Good API
@schneidenbach#NeverRest
Do what makes sense. Throw out the rest.
Is that vague enough for you?
@schneidenbach#NeverRest
MaintainDocument
ImplementDesign
API Design Process
@schneidenbach#NeverRest
Designing your RESTful API
I HAVE ONE RULE… okay I actually have two rules
@schneidenbach#NeverRest
(or, Keep it Simple, Stupid)
@schneidenbach#NeverRest
KISS
Don’t be creative.
Provide what is necessary – no more, no less.
Use a handful of HTTP status codes.
@schneidenbach#N...
403 Forbidden
(aka you can’t do that)
401 Unauthorized
(aka not authenticated)
404 Not Found
400 Bad Request201 Created200...
KISS
{
"id": 1234,
"active": true,
"nameId": 345
}
{
"id": 345,
"name": "Acme"
}
Customer API Name API
GET /customers/1234...
KISS
That’s TWO REQUESTS per GET
That’s TWO REQUESTS per POST
What’s the point?
@schneidenbach#NeverRest
Don’t let your specific
implementations leak if they are
hard to use or understand.
@schneidenbach#NeverRest
KISS
{
"id": 1234,
"active": true,
"name": "Acme"
}
Customer API
GET /customers/1234
@schneidenbach#NeverRest
KISS
Theory
Annex
Threshold
Lilia
@schneidenbach#NeverRest
KISS
Inactive
Deleted
Visible
Retired
@schneidenbach#NeverRest
Second big rule – Be Consistent
Be consistent with accepted best practices.
Be consistent with yourself.
@schneidenbach#Ne...
PATCHDELETE
POSTPUTGET
Understanding verbs
Remember consistency!
@schneidenbach#NeverRest
Don’t mutate data with GETs.
@schneidenbach#NeverRest
Resource identification
Nouns vs. verbs
Basically, use plural nouns
@schneidenbach#NeverRest
{
"invoices": [
{ ... },
{ ... }
]
}
GET
/customers/1234/invoices
GET /customers/1234
?expand=invoices
Within the parent o...
GET considerations
Sorting
Filtering
Paging
@schneidenbach#NeverRest
Sorting/Ordering
$orderBy=name desc
$orderBy=name desc,hireDate
@schneidenbach#NeverRest
Filtering
$filter=(name eq 'Milk' or name eq 'Eggs') and price lt 2.55
@schneidenbach#NeverRest
Sorting and filtering for free
Google “OData web api”
@schneidenbach#NeverRest
Paging
GET /customers? page=1 & pageSize=1000
{
"pageNumber": 1,
"results": [...],
"nextPage": "/customers?page=2"
}
Good ...
Do I need to sort/page/filter?
Maybe!
What do your consumers need?
@schneidenbach#NeverRest
Versioning
Your APIs should stand a test of time
@schneidenbach#NeverRest
Versioning
GET /customers
Host: contoso.com
Accept: application/json
X-Api-Version: 1
@schneidenbach#NeverRest
POST /custo...
Versioning
Use URL versioning
@schneidenbach#NeverRest
GET /v1/customers
Host: contoso.com
Accept: application/json
Error reporting
Errors are going to happen.
How will you manage them?
@schneidenbach#NeverRest
Error reporting
{
"name": "Arana Software"
}
@schneidenbach#NeverRest
Requires name and state
POST /vendors
400 Bad Reques...
Error reporting
@schneidenbach#NeverRest
Error reporting
Make finding and fixing errors as easy
on your consumer as possible.
@schneidenbach#NeverRest
AuthenticationEncryption
Security
@schneidenbach#NeverRest
Use SSL.
Don’t roll your own encryption.
Pick an auth strategy that isn’t Basic.
@schneidenbach#NeverRest
Security
Ok, time for some code examples
and practical advise
@schneidenbach#NeverRest
@schneidenbach#NeverRest
Controller Anatomy
@schneidenbach#NeverRest
@schneidenbach#NeverRest
@schneidenbach#NeverRest
Use DTOs/per-request objects
@schneidenbach#NeverRest
Separation of concerns
@schneidenbach#NeverRest
@schneidenbach#NeverRest
@schneidenbach#NeverRest
Separation of concerns
@schneidenbach#NeverRest
Controllers should know “where,” not ”how.”
@schneidenbach#NeverRest
Validation
@schneidenbach#NeverRest
Validation
Validate. Validate. Validate.
@schneidenbach#NeverRest
Separate validation logic from object.
Google Fluent Val...
Controller
Good Architecture
Request Handler/ServiceValidator
Enforce separation of concerns for
maintainability and testa...
Gotchas/ErrorsFormatting
SchemaParametersEndpoints
Documentation
@schneidenbach#NeverRest
Documentation
A good API lives and dies by its
documentation.
(you should tweet that out)
@schneidenbach#NeverRest
Maintaining your API
Vendor: “Hey, we’ve made some under-the-cover changes to our
endpoint. It shouldn’t impact you, but l...
Maintaining your API
Fix bugs and optimize.
Don’t introduce breaking changes like
removing properties.
@schneidenbach#Neve...
Thank you!
Slides, resources at rest.schneids.net
schneids.net
@schneidenbach
You’ve finished this document.
Download and read it offline.
Upcoming SlideShare
Best Practices for Architecting a Pragmatic Web API.
Next
Upcoming SlideShare
Best Practices for Architecting a Pragmatic Web API.
Next
Download to read offline and view in fullscreen.

Share

RESTful API Design Best Practices Using ASP.NET Web API

Download to read offline

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.

Related Books

Free with a 30 day trial from Scribd

See all

Related Audiobooks

Free with a 30 day trial from Scribd

See all

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
  • JohnAttebury1

    Aug. 9, 2020
  • uselessaccount1

    Feb. 1, 2019
  • hema3rafa

    Jan. 25, 2019
  • KleberAparecido

    Nov. 27, 2018
  • orijitbanerjee

    Jun. 26, 2018
  • AntonSavchenko3

    Jun. 23, 2018
  • jhattat

    May. 28, 2018
  • bogdanduduman

    Jan. 25, 2018
  • ramupatil

    Oct. 31, 2017
  • wieliong

    Aug. 17, 2017
  • FilippoBabolin

    Jul. 18, 2017
  • amvir

    Jul. 12, 2017
  • ModiChirag1

    Jun. 24, 2017
  • BrijeshPal

    Apr. 11, 2017
  • ssuser365b45

    Mar. 25, 2017
  • RohanRasane

    Feb. 6, 2017
  • somchaipatt

    Jan. 24, 2017
  • alaa001

    Dec. 19, 2016
  • weideng1485

    Dec. 13, 2016
  • ericardezp

    Jul. 26, 2016

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.

Views

Total views

8,031

On Slideshare

0

From embeds

0

Number of embeds

13

Actions

Downloads

381

Shares

0

Comments

0

Likes

20

×