4 ms·

Great article. I'm actually in the middle of building out a new API. I've built many RESTful APIs but I'm starting to rethink of a couple of things with this ne

by vyrotek 13y ago

Great article. I'm actually in the middle of building out a new API. I've built many RESTful APIs but I'm starting to rethink of a couple of things with this new one. Does anyone have any good resources on when it's NOT appropriate to use REST? Or is the assumption that it should generally work for anything if you model it right? I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests. In fact, they are a lot of verbs which fire off lots of business logic and don't really map well to a single entity. Some endpoints also need to return very large and deeply filled entities in a single call. I've started to investigate JSON-RPC, is that a good option?

dragonwriter 13y ago
> Or is the assumption that it should generally work for anything if you model it right? It should generally work for anything if you model it right. > I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests. How can anything both be an action and not be a state change request? > In fact, they are a lot of verbs which fire off lots of business logic and don't really map well to a single entity. A "verb that firest off lots of business logic" sounds like a RPC-style metaphor. In a REST architecture -- and they don't necessarily map perfectly so with more description I might characterize this differently -- I'd characterize that as most likely a entity creation (HTTP POST) action (the entity being a particular invocation of the underlying logic, and containing all the necessary parameters.) > Some endpoints also need to return very large and deeply filled entities in a single call. How does this conflict with REST. REST has nothing against "large and deeply filled entities". (Remember that HTTP is itself a RESTful API, and obviously is designed for a use case where "large and deeply-filled entities" are frequently returned.) You may want to define specific media types for each of these types of entities to do REST properly, but since in practice you are going to have to define the structure of the entity returned no matter what application architectural style you are using, this isn't really a substantial extra workload for REST.
- ebiester 13y ago
  I can think of an example: Send a message to the server to process all approved cases, which has no connection to an individual resource. The client has no fundamental knowledge of all server-side resources that may or may not be affected, and may not even be allowed that information. It's an action, but it's not really a post. You're not creating a new resource. You're not patching anything, you're not really getting anything... It's closest to a PUT, but you're not really updating a particular resource... This may not be a document-based API like REST expects, but it is a fairly common enterprise requirement for a system.
  - dragonwriter 13y ago
    > Send a message to the server to process all approved cases, which has no connection to an individual resource. "Individual resources" are defined by the needs of the API. If you need an endpoint that can be given a command to process all approved cases, then that is an "individual resource". The particular kind of resource I'd normally model it as is one which is or has a collection resource in which individual command instances are the members of the collection. > It's an action, but it's not really a post. I disagree. Submitting a new request to initiate the action is exactly a request to create a new command resource subordinate to the collection of commands subordinate to the command processing endpoint resource, which naturally maps to an HTTP POST action to the collection. The processing of approved cases, and the resulting changes to the backend data store, are consequences (side effects) of the creation of that resource. > This may not be a document-based API like REST expects REST doesn't expect a "document-based API". It expects a resource based API. Commands, collections of commands, and endpoints which have collections of commands as well as other subordinate resources are all, themselves, valid resources, whether or not they are sensibly described as "documents".
    - vyrotek 13y ago
      "REST doesn't expect a "document-based API". It expects a resource based API. Commands, collections of commands, and endpoints which have collections of commands as well as other subordinate resources are all, themselves, valid resources, whether or not they are sensibly described as "documents"." Ah, well said. It's so hard to find good examples of this though. Most REST tutorials focus on simple nouns that happen to map nicely to tables. But you're suggesting that "resources" could be far more abstract. But, if I were to treat Commands as resource and perhaps make it my only resource, isn't that essentially RPC?

by vyrotek 13y ago

dragonwriter 13y ago

> Or is the assumption that it should generally work for anything if you model it right? It should generally work for anything if you model it right. > I ask this because the API I'm building is for a B2B product and lot of the "actions" are not state change requests. How can anything both be an action and not be a state change request? > In fact, they are a lot of verbs which fire off lots of business logic and don't really map well to a single entity. A "verb that firest off lots of business logic" sounds like a RPC-style metaphor. In a REST architecture -- and they don't necessarily map perfectly so with more description I might characterize this differently -- I'd characterize that as most likely a entity creation (HTTP POST) action (the entity being a particular invocation of the underlying logic, and containing all the necessary parameters.) > Some endpoints also need to return very large and deeply filled entities in a single call. How does this conflict with REST. REST has nothing against "large and deeply filled entities". (Remember that HTTP is itself a RESTful API, and obviously is designed for a use case where "large and deeply-filled entities" are frequently returned.) You may want to define specific media types for each of these types of entities to do REST properly, but since in practice you are going to have to define the structure of the entity returned no matter what application architectural style you are using, this isn't really a substantial extra workload for REST.

ebiester 13y ago
I can think of an example: Send a message to the server to process all approved cases, which has no connection to an individual resource. The client has no fundamental knowledge of all server-side resources that may or may not be affected, and may not even be allowed that information. It's an action, but it's not really a post. You're not creating a new resource. You're not patching anything, you're not really getting anything... It's closest to a PUT, but you're not really updating a particular resource... This may not be a document-based API like REST expects, but it is a fairly common enterprise requirement for a system.
- dragonwriter 13y ago
  > Send a message to the server to process all approved cases, which has no connection to an individual resource. "Individual resources" are defined by the needs of the API. If you need an endpoint that can be given a command to process all approved cases, then that is an "individual resource". The particular kind of resource I'd normally model it as is one which is or has a collection resource in which individual command instances are the members of the collection. > It's an action, but it's not really a post. I disagree. Submitting a new request to initiate the action is exactly a request to create a new command resource subordinate to the collection of commands subordinate to the command processing endpoint resource, which naturally maps to an HTTP POST action to the collection. The processing of approved cases, and the resulting changes to the backend data store, are consequences (side effects) of the creation of that resource. > This may not be a document-based API like REST expects REST doesn't expect a "document-based API". It expects a resource based API. Commands, collections of commands, and endpoints which have collections of commands as well as other subordinate resources are all, themselves, valid resources, whether or not they are sensibly described as "documents".
  - vyrotek 13y ago
    "REST doesn't expect a "document-based API". It expects a resource based API. Commands, collections of commands, and endpoints which have collections of commands as well as other subordinate resources are all, themselves, valid resources, whether or not they are sensibly described as "documents"." Ah, well said. It's so hard to find good examples of this though. Most REST tutorials focus on simple nouns that happen to map nicely to tables. But you're suggesting that "resources" could be far more abstract. But, if I were to treat Commands as resource and perhaps make it my only resource, isn't that essentially RPC?