RESTful API Design Best Practices Using ASP.NET Web API

#NeverRest
RESTful API Design Best Practices
Using ASP.NET Web API
Spencer Schneidenbach
@schneidenbach

Slides, links, and more at
rest.schneids.net
@schneidenbach#NeverRest

Developers have the power of choice

Long-term benefits
Go from 0 to “make magic happen”
Learn stuff and manage exceptions

Developers have an opportunity create
something better than the competition

API Design is UX for Developers

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

Some common themes

Simple != Easy

There’s No Silver Bullet

What is REST?
Representational State Transfer

Uniform Interface
Code on Demand
(optional)
Layered
StatelessCacheableClient-Server
The Six Constraints of REST

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

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

Pragmatic REST
RESTful API != Good API

Do what makes sense. Throw out the rest.
Is that vague enough for you?

MaintainDocument
ImplementDesign
API Design Process

Designing your RESTful API
I HAVE ONE RULE… okay I actually have two rules

(or, Keep it Simple, Stupid)

KISS
Don’t be creative.
Provide what is necessary – no more, no less.
Use a handful of HTTP status codes.

403 Forbidden
(aka you can’t do that)
401 Unauthorized
(aka not authenticated)
404 Not Found
400 Bad Request201 Created200 OK
Good HTTP Codes

KISS
{
"id": 1234,
"active": true,
"nameId": 345
}
{
"id": 345,
"name": "Acme"
}
Customer API Name API
GET /customers/1234 GET /names/345

KISS
That’s TWO REQUESTS per GET
That’s TWO REQUESTS per POST
What’s the point?

Don’t let your specific
implementations leak if they are
hard to use or understand.

KISS
{
"id": 1234,
"active": true,
"name": "Acme"
}
Customer API
GET /customers/1234

KISS
Theory
Annex
Threshold
Lilia

KISS
Inactive
Deleted
Visible
Retired

Second big rule – Be Consistent
Be consistent with accepted best practices.
Be consistent with yourself.

PATCHDELETE
POSTPUTGET
Understanding verbs
Remember consistency!

Don’t mutate data with GETs.

Resource identification
Nouns vs. verbs
Basically, use plural nouns

{
"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

GET considerations
Sorting
Filtering
Paging

Sorting/Ordering
$orderBy=name desc
$orderBy=name desc,hireDate

Filtering
$filter=(name eq 'Milk' or name eq 'Eggs') and price lt 2.55

Sorting and filtering for free
Google “OData web api”

Paging
GET /customers? page=1 & pageSize=1000
{
"pageNumber": 1,
"results": [...],
"nextPage": "/customers?page=2"
}
Good paging example on my blog: rest.schneids.net

Do I need to sort/page/filter?
Maybe!
What do your consumers need?

Versioning
Your APIs should stand a test of time

Versioning
GET /customers
Host: contoso.com
Accept: application/json
X-Api-Version: 1
POST /customers
Host: contoso.com
X-Api-Version: 2.0

Versioning
Use URL versioning
GET /v1/customers
Host: contoso.com

Error reporting
Errors are going to happen.
How will you manage them?

Error reporting
{
"name": "Arana Software"
}
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."
}

Error reporting

Error reporting
Make finding and fixing errors as easy
on your consumer as possible.

AuthenticationEncryption
Security

Use SSL.
Don’t roll your own encryption.
Pick an auth strategy that isn’t Basic.
Security

Ok, time for some code examples
and practical advise

Controller Anatomy

Use DTOs/per-request objects

Separation of concerns

Separation of concerns
Controllers should know “where,” not ”how.”

Validation

Validation
Validate. Validate. Validate.
Separate validation logic from object.
Google Fluent Validation

Controller
Good Architecture
Request Handler/ServiceValidator
Enforce separation of concerns for
maintainability and testability.
Google MediatR

Gotchas/ErrorsFormatting
SchemaParametersEndpoints
Documentation

Documentation
A good API lives and dies by its
documentation.
(you should tweet that out)

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

Maintaining your API
Fix bugs and optimize.
Don’t introduce breaking changes like
removing properties.

Thank you!
Slides, resources at rest.schneids.net
schneids.net
@schneidenbach

RESTful API Design Best Practices Using ASP.NET Web API

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to RESTful API Design Best Practices Using ASP.NET Web API

Similar to RESTful API Design Best Practices Using ASP.NET Web API (20)

Recently uploaded

Recently uploaded (20)

RESTful API Design Best Practices Using ASP.NET Web API

Editor's Notes