Just like gRPC and GraphQL, this breaks HTTP-based mechanisms like GET request caching (since there are no GET requests anymore). Request data is always passed in the request body as JSON.For example /users/get, /users/list or /users/update. Every endpoint has an associated path that clearly describes what it does, without any dynamic path parameters. ![]() Every endpoint uses the HTTP POST method.One approach I have rarely seen discussed, perhaps because REST advocates would consider it heresy, is to build a JSON API that deliberately breaks away from REST principles: JSON over POST. They each come with a rich ecosystem of developer tools that can make them significantly more pleasant to use than REST on a daily basis. GraphQL and gRPC are both great options for designing an API. Again, there is no network-level caching. It also breaks away from HTTP semantics: both queries and mutations occur over POST. In fact, it always hits the same URL, typically /graphql. GraphQL is conceptually and functionally very different from gRPC, but it does have one thing in common: it exclusively uses POST. The URL matches the procedure's unique identifier, such as /PersonSearchService/Search. Each RPC maps to a POST request over an HTTP/2 connection (see Wireshark analysis). There is no network-level caching-instead it's an application-level responsibility. There is no distinction between querying data or mutating it. With gRPC, every request is a Remote Procedure Call. GraphQL and gRPC are very different in that they both do away with HTTP semantics. Unfortunately, it will be years before we can use it. That one now looks abandoned, but there is another proposal to introduce a QUERY method. In fact, a new HTTP method called SEARCH was drafted in 2015 to solve this problem. This can lead to endless arguments and ensuing confusion. Some backend frameworks such as Node.js interpret a repeated query parameter as a list, whereas others like Ruby on Rails require the query parameter name to end with, or else only the first (or maybe last?) value will be used. You could use query parameters, but you will quickly find that there is no universally accepted format to represent structured data in URLs. This can be problematic when implementing relatively complex endpoints such as /users/search. Request bodies aren't meant to be used in GET and DELETE endpoints. That is, there are three possible ways of passing data to a REST endpoint (four if you count headers). REST also means that request parameters are split up between path parameters ( /users/123), query parameters ( /users?limit=100) and a request body, depending on the endpoint. In my last job, we ended up spending several weeks of engineering time writing a detailed guide to designing RESTful endpoints with step-by-step decision trees, so that we could settle all debates once and for all. ![]() You may find yourself having a lot of debates with your team members about exactly how to design a specific endpoint, which HTTP method to use (POST, PUT or PATCH?), and so on and so forth. However, designing a true REST API can be quite difficult. REST also brings a consistent structure to your endpoints, thanks to resource-based namespacing such as /users/:id. For example, most clients will automatically cache the response of GET requests when the server returns the appropriate headers. There are advantages to following REST principles. REST is based on HTTP semantics, which strictly specify the meaning of each HTTP method (GET, POST, PATCH, PUT, DELETE and so on). JSON-based APIs are generally RESTful, or at least "REST-like". Most languages and tools offer at least rudimentary support for sending and receiving JSON payloads over HTTP(S). ![]() JSON-based REST APIs are the most common out there, presumably because you don't need to spend any effort setting up any particular library or tooling. Options abound, with Apache Thrift being yet another one. Or maybe you could go the gRPC route and leverage the efficient binary serialisation of Protocol Buffers. Or you could embrace GraphQL and its rich ecosystem to let API clients perform personalised queries while reducing unnecessary bandwidth usage and database queries. You could go old school and design a REST API, most likely using JSON. What if all your API endpoints exclusively used POST with JSON payloads instead of trying to follow REST?Īs a software engineer designing an API service, whether it's an internal backend service or a public web API, you have a plethora of API paradigms to pick from.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |