Rest – Custom functions in a REST API

apiapi-designrest

Looking at two of our entities Company and Address. A company has a billingAddress and a profileAddress.

I'm unsure of how to implement a function to set the billing address versus the profile. Here are the options I can see:

Create a new address using a POST to /address. Update the company object at /company with profileAddress = {/* the new id of the address */}
Execute /company/:id?function=updateBillingAddress&{/* rest of parameters go here */}
Execute /updateBillingAddress?company={companyId}&{/* rest of parameters go here */}
Execute /company/:id?billingAddress={ /* address data here */ }

The first method requires two calls and more responsibility on the part of the developer hooking up to the API. However, I'm not sure the second two methods are appropriate structure.

The last one seems like it might be okay, it gives flexibility for updates without holding the responsibility of managing pointers or executing two calls.. still unsure.

Has anyone seen use of methods 2 or 3 before. Are they okay to use? Why / why not? Which would you suggest to use and why?

Best Answer

In my mind, you have two different ways to handle this:

1) One resource to rule them all:

To create a new company:

 `POST /company`

POST body has full details of the company, including both profile address and billing address. As noted by v0idnull, return value should be a 201 Created with a Location header with the URL of the newly created resource.

To set the billing address:

Fetch the current company representation:

GET /company/123

Update the representation with the new billing address, and do:

PUT /company/123

With the full new representation of the company.

PROS

Reduce the number of requests for some workflows.
Caching is "easier" as you need to only worry about the caching of the one resource.
Easier to understand for more API customers.

CONS

If you have frequent updates to the company resource for different reasons, you can hit issues with concurrent updates
No ability to have fine grained cache control for the different aspects of the company.

2) Separate sub-resources for billing address and profile address

To create a new company:

POST /company

Response looks something like:

201 Created
Location: /company/123
Link: </company/123/billing_address>;rel=billing_address
Link: </company/123/profile_address>;rel=profile_address

Clients can then follow the billing_address or profile_address link relations to update those attributes respectively.

PROS

Allows fine grained updates to different aspects of the company with potentially less concurrent update failures.
Fine grained caching of each resource.
By using hypermedia/links, can restructure URLs/application later.

CONS

Requires multiple requests for many workflows (Mobile clients?)
Harder to grok for some API consumers not familiar with hypermedia APIs.

Related Solutions

RESTful Applications – Managing Cross Resource Operations

I highly recommend reading RESTful Webservices, especially the chapters on the difference between RESTful and RPC style web programming; and the chapters on resource discovery and how to deal with the apparent need for "verbs" (they are usually a different resource in disguise).

Converting an enquiry to a customer does not need a "convert" verb. You wouldn't delete the enquiry just because you create a customer and thus you are simply creating a customer with the information from the enquiry as input.

POST /users/{userId}/customers?enquiry={EnguiryId}

or simply

POST /users/{userId}/customers

with the enquiry information in the request body.

By the way, I use POST on customers because that is the way to do it if the server application is in control of the identifier generation. Only use PUT to create resources if the caller is the one determining the identifiers.

On a side note: have you considered the security and privacy issues relating to including /users/{UserId} in your URI's? Anybody can now start trying different userid's to get at information of different users of your application. You really should consider leaving them off your URI's and having them determined by the authentication information that should be send with each request (and possibly refreshed with each response).

PHP API Design – Chain-of-Command/Responsibility Pattern for Simple API: A Good Idea?

The idea of the chain-of-command pattern is to build a chain of handlers and pass a command along this chain until one of the handlers handles the command. This behavior is typically found in event processing, where, say, a click event from a UI button bubbles up the hierarchy of UI elements till it reaches an element that has a respective handler attached. This handler can then decided whether it handles the command -- effectively ending the event processing -- or not -- in which case the event is propagated further along the chain.

Let's now assume we use that pattern for you web API. What you describe sounds like a classical CRUD(L) interface to me, where your actions are (a subset of) create, read, update, and delete. You say you have delete requests and I'm assume that you want some kind of update requests, too. Let's assume further that you wrote respective handlers hupd and hdel for these kinds requests. Following the chain-of-command pattern, you then build the chain [hupd,hdel] to handle requests to your API. What happens is that every update request passed into the chain gets immediately handled by hupd, while every delete request is rejected by hupd and passed along to hdel, which handles it. This behavior shows a fixed mapping between actions and handlers that actually makes the chain unnecessary. (In fact, the chain even lowers your system's performance, because of the check and the passing along of every delete request). Why does this happen? Because there are no two handlers responsible for different subsets of requests with the same action type. What you really want to have here is a direct mapping ["update" => hupd, "delete" => hdel] and a dispatcher that takes respective requests and passes them directly to the respective handler. Such a design can still be extendible with regard to new actions, if there is a dynamic registry holding the mapping.

Now you could say, that you want to have different handlers for, say, the deletion of elements of type A and B. What gives you handlers for subsets of requests with the same action type. But once again, you have a direct and fixed mapping between the handlers and the element type, i.e., you can repeatedly dispatch requests based on the target element type. This gives you a two-level dispatch, where with a chain-of-command you would pass the request through number-of-actions times number-of-element-types handlers, in the worst case.

Conclusion: I would not recommend the chain-of-command pattern to implement this kind of API. For the pattern to have value, you need a scenario where you want to dynamically add and remove handlers and where the condition of when a handler actually handles an event is not expressible by a simple mapping from constants.

Best Answer

PROS

CONS

PROS

CONS

Related Solutions

RESTful Applications – Managing Cross Resource Operations

PHP API Design – Chain-of-Command/Responsibility Pattern for Simple API: A Good Idea?

Related Topic