I'm building a RESTful service with Symfony2.
It has a search function which returns a search entity, the entity has an array of results.
If the user performs an improper search there are a few different messages I may need to send them. Thus, My thought on how to structure the response is:
For a good search:
{
"message": "OK",
"search": <insert search object here>
}
and for a bad search:
{
"message: "Please double check your search in such and such fashion"
}
Essentially, always sending a "message" but not always sending a search entity, as one will not have been created if their search failed in certain ways.
Then, I will always return a 200 response, even when their search criteria were off. Or, if there were no results.
Does this jive with the thinking behind REST, or should I be changing the response to a 404 or something?
Thanks!
I think it depends on how you want to structure your RESTful service. When you say If the user performs an improper search to me that sounds like the user is using bad syntax in the search or doing something else wrong, as opposed to a properly formatted search that simply returns no results.
If that's the case I think most REST services return 400 - bad request, or some other error code in the 400 range.
Also, I think most REST services would return the search entity in the response body.
Related
We are currently trying to come up with a set of REST API that would fit our resource models.
A simplified example of the resource is:
CompanyInfo: {
totalNumberOfEmployees: Number,
employees: [...employees],
}
Employee: {
name: String,
}
In this case, "CompanyInfo" is like a virtual resource that does not exist in DB. It is a short cut for getting all the data related to the Company resource. The idea was to reduce the amount of logic on FE and create more convenient endpoint instead.
Our current endpoint design is:
GET /api/companyInfos/{companyId}/employees
GET,POST,PUT,DELETE /api/companyInfos/{companyId}/employees/{employeeId}
The reason for the extra {companyId} is because these endpoint does not return "Employees", it instead return a "CompanyInfo" that contains "Employees" embedded in the payload.
This is to avoid the aggregated property "totalNumberOfEmployees" not being updated in case sync when we call POST to create a new "Employee"
So my questions are:
Is this the correct approach to the problem of "too many requests" or "too much logic in FE"?
Is it acceptable for the endpoint to return a completely different resource than what its url describe?
Thanks a lot :)
For your Fist question
Is this the correct approach to the problem of "too many requests" or "too much logic in FE"?
yes Sometimes this is how it is suppose to be done. when data sent is small in each request. to many request does not affect the performance so This is how it is suppose to be done .
And Generally it is recommended to write one monolithic Ajax call in front end which will be capable of making any kind of call , By taking callback as parameter, and method , arguments as parameters .
So it will not be to much of logic if you follow this approach . All you have to write is callback for each of Ajax call . How ever sometimes situation may not allow for this Example:if you are using content-type like 'multipart/mixed'
there you have to write another ajax call code
However nowdays most front end has too much of logic based on how interactive website is . So your primary concern should be about look of web site .
For you second question
Is it acceptable for the endpoint to return a completely different resource than what its url describe?
yes . It is acceptable . but it is recommended that client mention all the MIME types which it expects in Accept header and Only those MIME types should be returned by Api.
We have stock website and we help buyers connect with the sellers. We are creating API to let buyers push their contact details and get back the seller details. This is transaction and get logged in our database. We have created following API:
The request is POST, the URL looks like:
/api/leads
The request body looks like:
{
"buyermobile": "9999999999",
"stockid": "123"
}
The response looks like:
{
"sellermobile" : "8888888888",
"selleraddress": "123 avenue park"
}
We have a new requirement, i.e. we need to send back PDF URL (instead of "sellermobile" & "selleraddress"). This PDF URL would contain the seller details in case it comes from one of our client.
We have modified the same API, now the request body looks like:
{
"buyermobile": "9999999999",
"stockid": "123",
"ispdf": true
}
The response looks like:
{
"sellerdetailspdf" : "https://example.com/sellerdetails-1.pdf",
}
Is it RESTFUL to do this? OR we should create separate API for getting response as PDF?
I wouldn't approach it this way. What happens when you need to add XLS? Do you add "isxls" to the request too?
Things I'd consider:
Use a mime type for content negotiation. Post the same request, and specify in the Accept header what you expect back - JSON, PDF, etc. You're then actually getting the report instead of a link to the report, which may or may not be better.
- or -
Include a link in the typical lead response.
{
"sellermobile" : "8888888888",
"selleraddress": "123 avenue park",
"_links": {
"seller-details-pdf": "https://example.com/sellerdetails-1.pdf"
}
}
- or -
Support a query parameter that specifies the type in the response.
- or -
Have a single property that specifies the type in the response, rather than a boolean. Much cleaner to extend when you add new response types.
The first two options have the bonus that you don't require clients to handle multiple response types to a single request. That's not forbidden by any spec, but it's annoying for clients. Try not to annoy the people who you want to pay you. :)
Again the implementation looks good to me, however you could potentially look at breaking the return of the PDF URL to another endpoint maybe something like api/lead/pdf that way your request body is the same for api/lead and all subsequent endpoints under /lead. Allowing your routes and other code to handle small portioned tasks instead of having a route that handles multiple flags and multiple code routes.
That looks good to me - the same type of input should give the same type of response but in your case you have two different types of input - one with the "ispdf" flag and one without. So it's consistent to responds with two different types of response, one with the PDF link and one without.
That's still something you'll want to document but basically it's a correct implementation.
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
The mojolicious application that I use is JSON based, that is the interaction between the client and the server is more of an exchange of JSON structured data.
I am trying to implement a standard way of handling errors with proper HTTP response code when an error occurs during one of the REST calls. What is the best way of implementing such a standard and where do I do it?
I see a couple of ways of doing it
Create a class and list all the error response and its associated content, a call could be made to this class with the response code, which would return the JSON structure(combination of hashes and arrays) containing all the associated entry, then use the render_json() method in controller and return this as a response to the client
I can create a table in the Database with entry for all the fields that are required for the response, use the filed to access the JSONstructure, create the appropriate response and use render_json() in controller and return this as a response to the client.
Example of error response might be like
{
"Message": "The requested resource is not found"
"Type" : "http://this.is.an.error.com/error/resource_not_found",
"ErrorCode" : 404,
"Created" : "2012-11-05T11:59:29-05:00",
"Request" : "GET /types/Foo/instances"
}
What is the right way of standardizing such a response?
As titanofold mentioned, I'd go for option 2.
Regarding error codes, try to stick with standard HTTP Response Status Codes.
Besides setting the ErrorCode property in your JSON, you should send the status code in the response header because:
you can treat errors in a single place - the error callback of your javascript function
in the future you might have other consumers of your backend (mobile apps for example)
this is why they have been invented
You can achieve that extremely simple with Mojolicious:
$self->render_json( {
Message => "The requested resource is not found",
Type => "http://this.is.an.error.com/error/resource_not_found",
ErrorCode => 404,
Created => "2012-11-05T11:59:29-05:00",
Request => "GET /types/Foo/instances",
},
status => 404);
The wonderful things about standards are that there are so many to choose from, and if you don't like any of them you can make your own.
As to the REST structure, that's up to you. I would go for the generic 'code' rather than 'ErrorCode' as you should return a code on success, too.
For your method options, I'd go with option 2.
I would also opt for option 2. But I do not understand the need for the error details to be part of the database. I would rather suggest you use a the OO concept of base class holding all the error details and the inheriting it to other classes, making sure you have access to it.
I have a list function that can be accessed like this:
_list/characters/characters_by_user?startkey=["org.couchdb.user:rodriguez"]&endkey=["org.couchdb.user:rodriguez", {}]
I'm attempting to rewrite the URL so you can access it in a friendlier way...
/rodriguez/characters
...by writing this rule:
{from: '/:user/characters', to: '_list/characters/characters_by_user',
query: {
startkey: "[%22org.couchdb.user%3A:user%22]",
endkey: "[%22org.couchdb.user%3A:user%22,%20{}]"
}
}
However, I get this error:
error: "query_parse_error",
reason: "No rows can match your key range, reverse your start_key and end_key or set descending=true"
Why would the query work correctly in the full URL, but not using the rewrite?
Update
I believe this may be a bug with the way CouchDB handles the encoded colon (%3A). I'm awaiting a response from the mailing list and will update this question accordingly.
I found that checking CouchDB's logs proved to be the best way to troubleshoot how URLs were being rewritten. Unfortunately, the issue I submitted to the CouchDB mailing list has yet to be replied to.
As a workaround, I've emitted the user's name without fully-qualifying it, which suits my purpose:
var user = doc.createdBy.split(":")[1];
emit(user, doc);