RESTful URLs for collection of objects

Question

I have an entity Temperature.

My URLs are designed as follows:

 GET     /api/temperatures/new
 GET     /api/temperatures/{id}/edit
 GET     /api/temperatures
POST     /api/temperatures
 PUT     /api/temperatures/{id}
DELETE   /api/monitoring/temperatures/{id}

I would like to create multiple temperatures (a collection of temperatures) at once - are there any conventions in terms of the urls to use?

So far, I came up with the following:

POST /api/monitoring/temperatures/collection
GET  /api/monitoring/temperatures/cnew

I thought there must be a convention for this already so would like to check with you.

Why don't you just send an array of temperatures using `POST` to the `/api/temperatures` endpoint? — cassiomolin, May 25 '16 at 09:43

kylieCatt · Answer 1 · 2016-05-27T18:30:08.340

GET     /api/temperatures  # Getting all resources
POST    /api/temperatures  # Create new resource
GET     /api/temperatures/<id>  # Get a single resource
PUT     /api/temperatures/<id>  # Edit all fields
PATCH   /api/temperatures/<id>  # Edit some fields
DELETE  /api/temperatures/<id>  # Delete a resource

These are the kinds of URL's Fielding describes in his thesis on REST. You shouldn't be describing what an end point does in the URL especially when used properly the HTTP verbs provide plenty of information. Be aware the REST architectural style has more to it than JSON over HTTP. Generic connectors, decoupling of components and a stateless server are key components of a RESTful application.

Note: Most people probably wouldn't implement both PUT and PATCH. PUT will be fine but I included it for completeness.

In response to your comment, if you are referring to creating multiple resources with one POST request you don't need a new URL. Your application should be able to handle {temp: 45, date: ...} and [{temp: 45, date: ...}, {temp: 50, date: ...}] at the same endpoint.

Suggest for what? If you need to create multiple new resources then you need to either send multiple POSTs or be able to handle POST requests that contain and array of new resources. — kylieCatt, May 26 '16 at 14:42
Great - now what URL would you post it to in the second scenario? — Mick, May 26 '16 at 23:38

score 0 · Answer 2 · edited May 23 '17 at 12:22

The HTTP method GET is not suitable for creating or editing resources - /api/temperatures/new and /api/temperatures/{id}/edit. HTTP GET is used for getting information without changing state in a server. You should use POST or PUT.

If you want to create multiple temperatures, you should use

POST /api/monitoring/temperatures

and consume JSON or XML list of objects.

Java example:

@POST
@Path("/temperatures")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response postTemperatures(Temperatures temperatures){
    // process and save
}

@XmlRootElement
public class Temperatures {

    public List<Temperature> temperatures;

    Temperatures(){}
}

JamesA · Answer 3 · 2016-05-26T08:31:44.177

You can update multiple entries with a single post by sending in an array of temperatures instead of a single entry,

POST     /api/temperatures  { [{...},{...}] }

but your api endpoint structure could be streamlined a little.

Ideally you want a simple consistent interface for all API resources.

I would personally simplify:

 GET     /api/temperatures/new
 GET     /api/temperatures/{id}/edit
 GET     /api/temperatures
POST     /api/temperatures
 PUT     /api/temperatures/{id}
DELETE   /api/monitoring/temperatures/{id}

to

 GET     /api/temperatures            // Get all temperatures
POST     /api/temperatures            // Send in array of new entries to update
 GET     /api/temperatures/{id}       // Read a specific temperature
 PUT     /api/temperatures/{id}       // Update a specific temperature
DELETE   /api/temperatures/{id}       // Delete a specific temperature

This gives a consistent interface to the api for all temperature related calls that maps onto a CRUD interface.

Without context its hard to work out exactly what /api/temperatures/new is used for, but I would consider using a parameter on the call for finegraining the response.

e.g.

/api/temperatures?age=new      // Get new temps

Which will allow you to use the common structure to add different types of criteria later on.

RESTful URLs for collection of objects

3 Answers3