What's the correct URI for a PUT REST request if i want to edit/update only one article?
Is it:
// PUT api/articles
or:
// PUT api/articles/id
UPDATE
I don't know if i can send the article id from the body with all other attributes (title, etc.) and emit the id from the URI or should i add it to the URI as well. But i guess that i got my answer already. Will have the id in the body and URI i guess.
If you're following REST principles, then the correct answer is, "Whatever you got back in the Location header from the POST request that created the resource". The basic idea is that the server assigns a URI path as the resource identifier when the resource is created. That path is what you then use in subsequent requests, including GET, PUT and DELETE, when you want to refer to the same resource.
If the resource you want to update is retrieved by doing a GET to /api/articles, then use /api/articles for your PUT request too. If you GET /api/articles/id, then use PUT /api/articles/id to make changes to it.
Based on what you are saying, I'm guessing you want to update or create a new article, not replace all articles.
PUT is used to replace the resource that you are targeting. This means that:
PUT api/articles
creates or replaces all your articles, and:
PUT api/articles/id
Creates or replaces the article 'id'.
Related
The Situation:
Via POST operation, users can create a new resource based on given parameters. If there already exists a resource created from these same parameters, the existing resource is returned instead.
Users are able to GET this resource if they know the resource ID (generated on creation, and is effectively random). I would like to provide users a way to check existence only knowing the creation parameters and without creating a new resource.
The Question:
Would it be RESTful to take some kind of "just-checking" property in the POST body to prevent a new resource from being created?
An Example:
POST vehicle
{
colour: 'red',
wheels: 4
}
201: {
vehicleId: '314-159',
colour: 'red',
wheels: 4
}
GET vehicle/314-159
200: {
vehicleId: '314-159',
colour: 'red',
wheels: 4
}
POST vehicle
{
colour: 'red',
wheels: 4,
check: true
}
200: {
vehicleId: '314-159',
colour: 'red',
wheels: 4
}
POST vehicle
{
colour: 'blue',
wheels: 8,
check: true
}
404: Not Found
Edit
Much of the discussion has been around whether the POST operation should be idempotent, which, while valid, does not address my question.
I would like to provide my users with a way to validate the existence of a resource based only on the properties that would be used to create the resource.
The idempotency of the POST method is irrelevant. What suffers from the absence of this check is subsequent GET requests which will contain a number of resources that are never intended to be used, and make it more difficult to find useful information.
A POST request containing a "do-not-create" flag would fill this need, but may not feel RESTful.
How about implementing an idempotent post? In doing so you could avoid the “check” body param.
2 ideas:
Use PUT and natural keys
One option (not sure if this works for you) is to not use some database-id in the url but use something that's a bit more like a natural key.
So instead of POSTing on some collection, you just PUT the item:
PUT /vehicles/colour/blue/wheels/8
PUT can also be used for creation just fine. And you could use a header such as this to prevent overwriting existing values:
If-None-Match: *
Don't put it on the client to do this
What if a POST for creating an item is identical to updating it? Or, what if you call POST on an existing item, it just doesn't actually do anything.
Maybe the client doesn't need to know if it just created a new item, or if the server already had that item.
Just make sure that for those 2 cases the server behaves the same, and you should be good.
Users are able to GET this resource if they know the resource ID (generated on creation, and is effectively random). I would like to provide users a way to check existence only knowing the creation parameters and without creating a new resource.
How would you do it with a web site?
Probably, with a form, that would accept as inputs the same creation parameters. The user is in effect performing a search, which is a semantically safe operation, so the form would likely use the GET method and have the arguments from the form encoded into the query string.
The endpoint, on receiving that request, could redirect it to the appropriate resource (if one already exists) or to another resource to handle the case when it doesn't.
Would it be RESTful to take some kind of "just-checking" property in the POST body to prevent a new resource from being created?
Sure - again, how would you do this on a web site? The form would have an extra checkbox, set to the correct default behavior, but giving the user the option to change it before submitting the form.
Because switching the check box changes the semantics from a safe operation to an unsafe operation, you might want to change the method on the form during submission -- HTML by itself doesn't do that, but you can do it with javascript aka code on demand.
Using POST for safe operations isn't ideal, because generic components can't tell that the operation is safe. This means that they can't know to automatically retry the request if the response is lost, they don't have the correct default cache behaviors, and so on.
For the record, the solution chosen was to add options for a special case on the GET method.
As touched on in this answer, it is not quite in the spirit of the POST method to perform this type of operation, and it muddies the model being presented to the users.
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.
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.
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(){}
}
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.
I've heard that in REST world, POST is recommended to create an entry, while PUT is recommended to update an entry.
First, I'd like a confirmation of this statement.
Then, using this assumptions, let's say I have a #POST method to create a user and a #PUT method to update a user (with a #QueryParam to pass the user ID).
What is the correct way to pass parameters to POST and PUT?
Is #FormParam appropriate for #PUT? Or should I pass a JSON in the body?
Should I pass parameters the same way for both #POST and #PUT or a different way?
Or should I use POST for both?
Edit: This question initially showed an example that did not work for me, but it was because my testing tool was doing it wrong. It works with POSTMAN now.
Yes, with REST, you typically use the following:
The method POST of the element list resource to add an element
The method PUT of the element resource to completely update an element
The method PATCH of the element resource to partially update an element
Since what you must send corresponds to the state of the resource, you have to provide it within the request body.
The two bodies (for adding and updating) is similar but there are some differences. For example, if you expect the RESTful service to autogenerate some fields, you don't have to provide corresponding ones.
Here are sample requests:
POST /contacts
{
"lastName": "my last name",
"firstName": "my first name",
}
(corresponding response status code: 201 - Created)
PUT /contacts/contactid
{
"lastName": "my last name",
"firstName": "my first name",
}
(corresponding response status code: 204 - No content)
You can notice that JSON isn't the only format you can use. XML, YAML, and so on could also be used.
I think that the following link could give you some hints:
Designing a Web API - https://templth.wordpress.com/2014/12/15/designing-a-web-api/
Hope it helps you,
Thierry
So nothing new here I am just trying to get some clarification and cannot seem to find any in other posts.
I am creating a new resource restulfully, say:
/books (POST)
with a body:
{
title: 'The Lion, the Witch and the Wardrobe',
author: 'C. S. Lewis'
}
I know that I should return a 201 (Created) with a Location header of the new resource:
Location: /books/12345
The question I cannot seem to answer for myself is what should the server return in the body.
I have often done this type of response:
{
id: 12345,
title: 'The Lion, the Witch and the Wardrobe',
author: 'C. S. Lewis'
}
I have done this for a couple reasons:
I have written api for front end frameworks like angularjs. In my
particular case I am using angular resources and I often need just
the id for the resource to locate it. If I did not return the id in
the response body I would need to parse it out of the Location
header.
In a GET of all books I usually return the entire object not just
the id. In this sense my client code does not have to differentiate
where to get the id from (location header or body).
Now I know I am really in the grey area here, but most people are saying that returning the entire resource is 'bad' practice. But what if the server changes/adds information to the resource. It definitely adds the id, but might also add other things like a timestamp. In the case that I do not return the entire resource, is it really better to do a POST, return the id, then have the client perform a GET to get the new resource.
Returning the new object fits with the REST principle of "Uniform Interface - Manipulation of resources through representations." The complete object is the representation of the new state of the object that was created.
There is a really excellent reference for API design, here: Best Practices for Designing a Pragmatic RESTful API
It includes an answer to your question here: Updates & creation should return a resource representation
It says:
To prevent an API consumer from having to hit the API again for an
updated representation, have the API return the updated (or created)
representation as part of the response.
Seems nicely pragmatic to me and it fits in with that REST principle I mentioned above.
Returning the whole object on an update would not seem very relevant, but I can hardly see why returning the whole object when it is created would be a bad practice in a normal use case. This would be useful at least to get the ID easily and to get the timestamps when relevant.
This is actually the default behavior got when scaffolding with Rails.
I really do not see any advantage to returning only the ID and doing a GET request after, to get the data you could have got with your initial POST.
Anyway as long as your API is consistent I think that you should choose the pattern that fits your needs the best. There is not any correct way of how to build a REST API, imo.
After a post I like to return something like this:
Response
.created(URI("/obj/$id"))
.entity(TheNewObj())
.build()
Status 201 - CREATED
Header Location - the location of the new object
Entity - the new object
I am working with REST in Yii. Therefore I use yiirestful plugin and Backbone.JS. At the moment I am perfectly able to do POST and GET request throughout REST. But when I want to update a record I alway get an 403 forbidden error. I shall explain what i've tried and how:
First of all I am saving my collection in Backbone like this:
Backbone.sync('update', this.collection);
Now I don't for sure if that's going to work but the fact is that any PUT request get's an 403.
Secondly, because I am working in a module I adjusted the URLmanager rules like this:
'contentManagement/api/<controller:\w+>'=>array('contentManagement/<controller>/restList', 'verb'=>'GET'),
'api/<controller:\w+>'=>array('<controller>/restList', 'verb'=>'GET'),
'api/<controller:\w+>/<id:\w+>'=>array('<controller>/restView', 'verb'=>'GET'),
'api/<controller:\w+>/<id:\w+>/<var:\w+>'=>array('<controller>/restView', 'verb'=>'GET'),
array('contentManagement/<controller>/restCreate', 'pattern'=>'contentManagement/api/<controller:\w+>', 'verb'=>'POST'),
array('<controller>/restUpdate', 'pattern'=>'contentManagement/api/<controller:\w+>/<id:\d+>', 'verb'=>'PUT'),
array('<controller>/restUpdate', 'pattern'=>'contentManagement/api/<controller:\w+>/<id:\d+>', 'verb'=>'PUT'),
array('<controller>/restDelete', 'pattern'=>'api/<controller:\w+>/<id:\d+>', 'verb'=>'DELETE'),
array('<controller>/restCreate', 'pattern'=>'contentManagement/api/<controller:\w+>', 'verb'=>'POST'),
array('<controller>/restCreate', 'pattern'=>'contentManagement/api/<controller:\w+>/<id:\w+>', 'verb'=>'POST'),
It could be the case that this causes the problem. But I am not very digged in to this rules.. I did the same as i did by the POST request but whatever I try it still gives the 403.
Thirdly i'll provide my request information:
PUT http://pimtest.php/Yii/trackstar/contentManagement/api/SidebarWidgetsUsed/
403 Forbidden
38ms
I think a id is needed after this url but when I provide an id in the data that should be enough to let backbone recognize it's about an PUT request / update request.
I have no clue where to look further in my code.. I understand it's a complicated story so any minimal advice is appreciated!
Greetz,
You have two (identical) rules that apply to PUT, and as you say, they require an ID. Without an ID, none of the rules will match for a PUT request.
Either provide an ID, or modify the rule to not require an id, e.g.:
array('<controller>/restUpdate', 'pattern'=>'contentManagement/api/<controller:\w+>', 'verb'=>'PUT'),
In any case, as you're not using id, I'm not sure why it's in the rule to start?