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.
7. Developers have an opportunity create
something better than the competition
@schneidenbach#NeverRest
8. API Design is UX for Developers
@schneidenbach#NeverRest
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
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
21. Designing your RESTful API
I HAVE ONE RULE… okay I actually have two rules
@schneidenbach#NeverRest
22. (or, Keep it Simple, Stupid)
@schneidenbach#NeverRest
23. KISS
Don’t be creative.
Provide what is necessary – no more, no less.
Use a handful of HTTP status codes.
@schneidenbach#NeverRest
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
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
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. Do I need to sort/page/filter?
Maybe!
What do your consumers need?
@schneidenbach#NeverRest
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."
}
66. Documentation
A good API lives and dies by its
documentation.
(you should tweet that out)
@schneidenbach#NeverRest
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. Maintaining your API
Fix bugs and optimize.
Don’t introduce breaking changes like
removing properties.
@schneidenbach#NeverRest
As an integrator, I see a lot of APIs that are good. I see far more that are bad. I’ve seen good SOAP APIs and bad ”REST” APIs.
Developers have the ultimate power – the power to choose. The power to influence. When you need to use a service, you want that service to be consistent, easy to use, and well-documented, among other things.
Developers have the ultimate power – the power to choose. The power to influence. When you need to use a service, you want that service to be consistent, easy to use, and well-documented, among other things.
Developers have the ultimate power – the power to choose. The power to influence. When you need to use a service, you want that service to be consistent, easy to use, and well-documented, among other things.
Think about the business you’re in. Think about the services your business could provide to external consumers if you have an API.
Now think about your competition. A good API can means the difference between a lead and a customer.
Think about the business you’re in. Think about the services your business could provide to external consumers if you have an API.
Now think about your competition. A good API can means the difference between a lead and a customer.
Simple means simple for your users. Think about the effort put into creating a user interface that’s easy to use.
Making it easy for developers to consume your API is not a trivial task. Requires lots of thinking, research, and design. Not to mention good documentation!
There’s no silver bullet, or one answer, to your API problems. Sometimes you’re limited by scalability.
It’s the architecture of the web
Error codes/API structure/HTTP principles (GET vs POST)
Error codes/API structure/HTTP principles (GET vs POST)
Note that I said A test of time, not THE test of time. An API should be built with some kind of lifecycle in mind. You will end up rewriting it later and
Encryption – use SSL, don’t roll your own (tell story about substitution cypher)
Authentication – talk about Basic vs OAuth
Error codes/API structure/HTTP principles (GET vs POST)
Controllers should know who needs to do something, not how to do it
Maintains a separation of concerns
Much more broken down and testable
Controllers should know who needs to do something, not how to do it
Maintains a separation of concerns
Much more broken down and testable
Controllers should know who needs to do something, not how to do it
Maintains a separation of concerns
Much more broken down and testable
Controllers should know who needs to do something, not how to do it
Maintains a separation of concerns
Much more broken down and testable
Error codes/API structure/HTTP principles (GET vs POST)
Great resource: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md
