I am creating an API and I wonder why it is common to have a id parameter in URI for PUT?
Such as PUT /cars/5
Why don't have PUT /cars? The request entity contains an id field isn't that enough? I can get the id from that entity, or is it some downsides to this, and is it considered bad to do it?
Because if you were to send a PUT request to /cars, semantically that would imply you are trying to modify attributes about the set of cars, rather than modifying attributes of an individual car. The URI in a RESTful API should indicate the exact resource the action is acting upon, so if you are modifying a resource, your URI should exactly indicate that resource.
Also, from RFC 2616:
The URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource.
So the spec indicates that if the client knows the resource's unique ID, it should be included in the URI.
this comes from rest "ideology".
the idea is that a url uniquely represents an entity - so you must PUT the entity youre creating/editing to the url of that entity.
to quote from the wikipedia page:
Identification of resources
Individual resources are identified in requests, for example using URIs in web-based REST systems. The resources themselves are conceptually separate from the representations that are returned to the client.
PUT aims to udpate ONE precised entity.
With merely using /cars, you aren't focus on a specific entity.
And on the contrary of what you wrote, your full entity isn't passed in a basic String (URI).
Excepted if your targeted method focus on a hard-coded car id ... but I don't think so..
It comes down to the API interface. There are several approaches to API design. And, like you suggested, you can leave the id out of the request. However, since many API designs are structured in a fashion you described, like PUT /cars/5, it`s considered good practise.
Basically, you have 8 ways to interact with your API. GET, POST, PUT, DELETE and an optional HEAD. ( if you count head, the total would be 9 or 10, depending on the interactions).
So, to clear it up, you have 2 ways of GET. GET /cars would retrieve all cars, GET /cars/5 would retrieve any car with an ID of 5.So, you have 2 ways of using GET. The same goes for POST, PUT and DELETE. 4*2 = 8 right?
Now, there are people who would say that PUT /cars would be ambigious, however you are completely valid in doing it without the extra ID field, because, as you mentioned, you are already passing in the ID field in the request.
The guys at Apigee have been researching API designs for a while now. I recommend watching some of their video`s to understand better what API design means and why some arguments are valid, and others are not.
Apigee Best practises
Related
I’m trying to find the best pracice on what type of response should I send when a path parameter in a REST service is blank or null when using a PUT method.
For example, imagine we have the following resource:
PUT report/{report-id}/client/{client-id}
Should I validate that the parameter report-id and client-id are not null or blank?
If they are blank or null I can think of two types of messages:
Return a 400 response with a message indicating that a mandatory
parameter is missing.
Return a 404 response, indicating that we can’t create or update the resource because that resource dosn’t exist?
I don't think there is a standard convention of doing it. Is there? However, I would like to hear opinions on what's the best practice to use in this case.
The specification for REST might be insightful here:
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
Since the lack of a resource cannot logically be given a name it can never exist in REST. As a consequence I think you'd find that most public APIs will return 404. Take getting a user's information from GitHub for example. The documentation states that a user can be found at https://api.github.com/users/{username}. https://api.github.com/users/ (notice the trailing slash) returns 404. Regardless of what the HTTP spec says (although following it is always a good idea) if you adhere to the principle of least surprise returning 404 is your best bet.
As a side note, when naming resources the convention is that collections should be plural. So, for your example you would actually want the resource to look more like: /reports/{report-id}/clients/{client-id}. Especially when dealing with 'empty' parameters it will make it much clearer exactly what the request was for.
I’m trying to find the best practice on what type of response should I send when a path parameter in a REST service is blank or null when using a PUT method.
An important thing to understand is that the body of the response is available to you to describe in detail what the actual problem is. See RFC 7231, section 6.5
the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.
The status code is metadata, which allows general-purpose components to understand what is going on. The metadata all belongs to the uniform interface, which is to say it is of the "transferring documents over a network" domain.
In this case, I think your best fit for a status code is 403 Forbidden
The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it.
I am building a REST API using JAX-RS. In angular front-end, I am sending the object to be deleted in the body of the HTTP request (JSON format). Now I need a way to map this HTTP DELETE body request which is containing the object that needs to be deleted to a local variable in the REST method.
For instance, on SPRING I did this by simply annotating an object variable with #RequestBody.
I was checking oracle's javaEE7 docs but the examples there are really basic and don't include complex objects, also the different tutorials that I found elsewhere were on the track of simple delete requests mapping a simple id with #PathParam.
Maybe before this question, the first question I should ask is whether sending the object in an HTTP's request body is at all a good approach? I was reading some articles which designated it as not such a good practice, although it is not explicitly forbidden. What would be the disadvantages of this approach?
I remember while I was researching about this method in SPRING, I read somewhere that malicious attacks could be possible by specially crafted user inputs (the persistence framework that I am using is JPA, EclipseLink).
Would it perhaps be better to map the primary key on a series of #Path variables and then map them using #PathParam?
So to sum up, first of all, is this a good approach?
And how can I read the object in the HTTP's request body?
Some pointers would be highly appreciated!
Unlike Spring MVC, JAX-RS does not define any annotation for the request payload.
The JAX-RS approach is slightly different: the value of the parameter not annotated with any #***Param annotations is mapped from the request entity body. Such parameter is called entity parameter.
The first question I should ask is whether sending the object in an HTTP's request body is at all a good approach?
Please refrain from doing that, as it's not how DELETE is supposed to work.
Find below a quote from the RFC 7231, the document that currently defines the semantics and content of the HTTP/1.1 protocol:
A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.
For interoperability, I advise you to stick to the standards as much as you can. And you definitely shouldn't be require to send any payload to identify the resource to be deleted.
Its primary key is 8 fields long.
The URI, which stands for Universal Resource Identifier, is meant to identify a resource.
As you have a bunch of fields that, in conjunction, identify a resource, I advise you to rethink your application design. You could, for example, introduce some sort of unique value to identify your resources. Have a look at UUID.
With JAX-RS you don't need a something like a #RequestBody.
You can simply add the class as parameter and it will be filled with the request body.
In you case passing the data in the body makes sense but how does your URL look like? As with REST you should have resources that are addressable by a URL
I am using Jersey as my RESTful Web Services framework.
I have made 2 new #GET REST calls in order to search objects in the database.
Those REST calls should serve 2 different components.
The first component has the user_id in its details.
The second component has the email in its details.
The email and the user_id are 2 different unique identifiers.
One option is to enable 2 different #GET REST calls with different paths such as:
".../api/users/search/id/:user_id"
".../api/users/search/email/:email"
In order to make is as simple as possible and much more general for future demands, I am looking for the way to merge those 2 REST calls to 1 path with different identifiers on in its QueryParam.
After searching for a good example followed by the best practices for such REST calls, I am not sure if such a merge is a good practice, or not.
The main issue I am not sure about is how to build the path as generic as can be.
The questions are:
Is it a good practice to merge those 2 different paths to 1 path in 1 REST call? if yes, please provide an example.
If it is a bad practice to merge those paths, how should I handle future features requests to search using new identifiers? the thinking of building new REST call for each identifier sounds problematic.
Well, one solution would be to add new queryParameters to the uri and thus enabling the users to use the same resource but with new parameters like for instance: /uri/search/email?aa#aa.com&user_id=userAdam.
Then you will on the server side need to take care of all these different scenarios in the same method. Thus you dive into the if/else/switch type of thing.
You will then have to handle to JSON objects returned. Obviously if you have a contract you need to follow it, thus if the client expects completely different responses it is hard to deliver them from one resource. So if the email query response is something significantly different than the user_id query response it might be hairy returning it from the same resource.
My 5 cents. Maybe I misunderstood you.
I am creating a RESTful webservice and I have a URL like this:
GET /pets
For normal users this should only return the pets that belongs to that user. But for admin it should return all pets in the system. Is this wrong to do? Or should I instead do this
GET /pets?ownedBy=Smith
and only allow access to the pets if the user is either Smith or an admin?
I don't think REST specifications mentions anything about it specifically. But IMPO, I believe it is perfectly right to return the results as per the requesting user. URLs should be kept as cleaner as possible. If user information is already present as part of headers, then it is not required to provide it in URL redundantly.
While answer from Juned Ahsan is perfectly correct IMHO, I would probably modify your URLs pattern to something like
GET /Smith/pets : return pets for Mr Smith
Authorization can now be done one layer up in the URL and URLs always represent the same resource. I tend to prefer this solution because it will be easier to add a caching layer on top of it. Adding the user (from HTTP header) to the cache key is not efficient, nor is it easy to configure for some caching solution.
I would only provide it in the URL if you also have cases where it is valid to put someone else's name there. For example if people are able to see their friends pet or if and admin is able to see a selected person's pets.
So in the situation where you have a user for that parameter it would make sense to expose it and always use it.
If that is not the case though then simplicity in your API is generally a good thing.
To answer the "can" in your question as well as the "should" though - it's entirely possible. Exactly how to implement it would depend on the framework you are using but they will all support this.
These two URLs are different.
The first one gives a list of pets.
The second one gives also a list of pets, but in this case the list is filtered by the property "owner".There is nothing wrong with this. I would change the second URL slightly to:
GET /pets?owner=Smith
The key with that this URL is, that the type of the result is the same (a list of pet entities), and the meaning is the same too. There is only a filter applied to the list. That is where the query is made for in REST.
In some cases a Path parameter would be better. If you have entities "person", which do have a property of type list of pets, I would create a path like
/<user>/pets
If the list of pets are the root elements I would use a query.
I think it is up to the implementation in the back-end service. Currently, I am working in a similar fashion on a WCF RESTful service (although for Android). And if you have some roles that you can add in your database, it is not so difficult to apply that in your service, and your url would have nothing to do with that.
Edit: If you do want to have something in the URL, you can always add that. But I do not think that it is necessary at all. The less the users see, the better.
As mentioned earlier by Christian Kuetbach using REST you would pass parameters separated by /
i.e. /<userid>/pets if you have any other user specific functionality, or maybe other way around /pets/<userid>. I would suggest using UUID as userID - this way it will ensure user details security
I am creating a web application that incorporates REST-style services and I wanted some clarification as to the preferred (standard) method of how the POST requests should be accepted by my Java server side:
Method 1:
http://localhost:8080/services/processser/uid/{uidvalue}/eid/{eidvalue}
Method 2:
http://localhost:8080/services/processuser
{uid:"",eid:""} - this would be sent as JSON in the post body
Both methods would use the "application/json" content-type, but are there advantages, disadvantages to each method. One disadvantage to method 2, I can immediately think of is that the JSON data, would need to be mapped to a Java Object, thus creating a Java object any time any user access the "processuser" servlet api. Your input is much appreciated.
In this particular instance, the data would be used to query the database, to return a json response back to the client.
I think we need to go back a little from your question. Your path segment starts with:
/services/processuser
This is a mistake. The URI should identify a resource, not an operation. This may not be always possible, but it's something you should strive for.
In this case, you seem to identify your user with a uid and an eid (whatever those are). You could build paths such as a user is referred to by /user/<uid>/<eid>, /user/<uid>-<eid> (if you must /user/uid/<uid>/eid/<eid>); if eid is a specialization, and not on equal footing with uid, then /user/<uid>;eid=<eid> would be more appropriate.
You would create new users by posting to /user/ or /user/<uid>/<eid> if you knew the identifiers in advance, deleting users by using DELETE on /user/<uid>/<eid> and change state by using PUT on /user/<uid>/<eid>.
So to answer your question, you should use PUT on /user/<uid>/<eid> if "processuser" aims to change the state of the user with data you provide. Otherwise, the mapping to the REST model is not so clean, possibly the best option would be to define a resource /user/process/<uid>/<eid> and POST there with all the data, but a POST to /user/process with all the data would be more or less the same, since we're already in RPC-like camp.
For POST requests, Method 2 is usually preferred, although often the resource name will be pluralized, so that you actually post to:
http://localhost:8080/services/processusers
This is for creating new records, however.
It looks like you're really using what most RESTful services would use a GET request for (retrieving a record), in which case, Method 1 is preferred.
Edit:
I realize I didn't source my answer, so consider the standards set by Rails. You may or may not agree that it is a valid standard.