In this video, Nate will dig deeper into the concepts behind REST, and contrast the REST and RPC styles of API design.
- Now that we've defined that a REST API represents resources and links between resources, let's dig deeper into this definition by contrasting it with another popular style of API design, RPC, or remote procedure call. In a RESTful API, the end points are nouns and represent resources that you can act on. For example, an end point that represents all the users in the system might be /users. In contrast, endpoints in an RPC API are verbs, because they represent functions or methods you can call on the server.
In a REST API, calling an endpoint acts on a resource using an HTTP method as a verb. For example, sending a get request to /users/123 retrieves the details of the user with that id. To update the user you might send a post request and a request body. You're still interacting with the same endpoint because the endpoint represents the resource or the object. An RPC API uses HTTP methods as well, but the semantics are a little different. The HTTP method may or may not correspond to the verb already in the endpoint name.
Calling an RPC API is very similar to calling a function in any programming language. You call the function by name, pass some arguments or perimeters, and get a response. In both styles, you'll get a response message back after you call an endpoint. In a REST API, the response contains the resource that you retrieved or changed. If your API call changed something on the server you should see that updated state in the response. In an RPC API, the response gives you the results of the function call. What that contains depends on how the API was designed and the context of the endpoint or function you called.
Note that both REST and RPC use HTTP methods, and both styles could return XML, JSON or some other format entirely. How they use those methods and what data structures they return is where the styles differ. The REST style means thinking about your API in a resource oriented way, compared to the RPC style of thinking about your API in a function oriented way. So, should you model your API with the REST style, or the RPC style? The answer is, it depends. It's important to remember that there isn't a perfect solution or rule that applies to every API.
Because every API is different, an API design isn't one size fits all. REST isn't a panacea, and neither is RPC or any other style. You should choose the style that best fits the goals and context of the API you need to build. Consider using the REST style when your API is data driven. In other words, your API needs to let clients retrieve and update data objects. And along the same lines, consider REST when you want to emphasize the links that exist between those resources and data objects. A good example of a REST API is the PayPal API, which lets clients create and manipulate objects that represent payments, invoices, billing plans and so on.
On the other hand, an RPC style might fit your API better if your API is action driven. For example, you need to send an event or command to a server or remote device. RPC API's are good when you need to design a strict set of ways the client can interact with the server. A popular example of an RPC API is the Slack API, which lets clients perform actions like joining a channel, and sending a message by sending function calls to the API. There's one more big piece to the REST puzzle, and that's the idea of self-documentation.
We'll talk about that next.
- REST vs. RPC
- Using HTTP methods (aka verbs)
- Returning JSON
- Creating a new API project
- Building a root controller
- Routing to controllers with templates
- Requiring HTTPS for security
- Creating resources and data models
- Returning data and resources from a controller
- Representing links (HREFs)
- Representing collections
- Sorting and searching collections
- Creating forms
- Caching and compression
- Authentication and authorization for RESTful APIs