i have question similar to this article ( Multiple optional query string parameters REST API GET ) but the given answers have 3 different opinion/answer and i dont know which one is the best practice to use, ive searched everywhere but cant find the definite answer.can someone please help me which answer is the right one and has a prove(trusted source that backing it up) that it is a best practice, sorry for bad english i hope you can understand what im saying,
The best way is to add filters in get request. Response in this post gives one example -
Best practice for filtering results from a RESTful API call?
In rest everything is a resource so if you want to filter items within same resource you can pass filter criteria along with pagination parameters. Generally only for separate resources we create a new API for optional parameters or to filter within same resource separate APIs should not be created. They are additional testing and maintenance cost.
To me answer #2 in the article makes most sense. You will be ok going with it
Related
Relationships
robot has many brains
brain has one robot
Background
How to form the resource URL where we provide a robotId (foreign key) to retrieve its brain?
I could come up with this resource:
GET /robots/:robotId/brain
I am not sure if using brain in singular is against REST conventions and practices.
However, using GET /robots/:robotId/brains (brain in plurals) implies a collection will be returned but it will always have 1 item only.
Question
Can you advise me on a RESTful way?
Can you advise me on a RESTful way?
REST doesn't care what spelling conventions you use for your resource identifiers.
Therefore, you should use whatever spellings make sense within your local context. That might mean, for your own convenience, that the spelling conventions that you use for your path segments are similar to those that you use when naming collections/tables in your data store. Or perhaps not - you could equally decide that, because the audiences differ, so too should the spelling conventions.
GET /robots/:robotId/brain
GET /robots/:robotId/brains
GET /brains/:robotId
GET /ee4fcf74-d494-4f90-8964-9e4d65aa61ef
These are all fine.
Stefan Tilkov's 2014 talk: REST: I don't Think it Means What You Think it Does may be helpful.
For me, you should have only 1 endpoint GET /robots/:robotId/brains, you will get all your collection, but your frontend have to processing your data like he want
If you have GET /robots/:robotId/brains this can still return a collection of size 1?
You should have a rest end point which gives you the collection of all the brains of a robot. The uri should look like this :
GET /robots/:robotId/brains
Number of items the collection has should not matter.
If the rest end point is GET /robots/:robotId/brain, you are very much ignoring the fact that a robot might have multiple brains in the future and if very much possible if you database supports a one to many relationship.
To get 1 brain of a robot you can always keep scope for the below rest uri: GET /robots/:robotId/brains/:brainId Where brainId is the unique/primary key for a brain.
This question already has answers here:
REST and complex search queries
(5 answers)
Closed 10 years ago.
So I am building a RESTful (as RESTful as I can) API with the Laravel 4 PHP Framework. Right now I have dozens of API calls working and I have a process for being to do limit, ordering, and do simple filtering. Here would be an example of one of the calls:
/api/v1/users?limit=10&offset=10&firstName=John&order[]=createdTimestamp desc
This would return the 11th through 20th users that have a first name of John ordered by the createdTimestamp in descending order. The simple filtering here can only does exact matches (=). Now I also want to be able to provide a more complex filtering system through the REST API that supports the ability to specific the equality match type that way they could do a != or > or LIKE, etc... The issue is that I don't know if I am going to be able to provide this type of filtering through a normal query string.
What is the best way to provide this complex filtering through a REST API? Is doing through a POST still considered the best way even though it is not "truly" RESTful (even though this would prevent issues of the user trying to run a long query that exceeds the URI character length limit that some browsers have)?
#ryanzec
Now I also want to be able to provide a more complex filtering system
through the REST API that supports the ability to specific the
equality match type that way they could do a != or > or LIKE, etc...
The issue is that I don't know if I am going to be able to provide
this type of filtering through a normal query string.
It's not possible with simple query string(well, maybe it's possible but is very hard to encode such logic properly in query string). You need to define custom query format and use POST to submit such query. Server may respond with:
"201 Created" status and "Location" header field indicating query resource if there was no such query before; or
"303 See Other" and "Location" header field indicating already existing query resource.
Is doing through a POST still considered the best way even though it
is not "truly" RESTful
I do not know who said this, but it's wrong. There is nothing wrong with using POST for such purposes.
Use forms in your collection resource responses to tell the client how to search the collections. See my answer to REST and complex search queries for examples.
I'm developing a rest API for our business system. We have the following resources so far:
/sales/orders
/sales/orders/{orderno}
/sales/order-items
There will be lots of resources when the API is finished, so we need to structure it in a good way to make it easy to understand. My question is: should /sales/order-items instead be /sales/orders/order-items? There is maybe no correct answer here, but what would you prefer?
One more question: The sales/order-items resource will list either all open items or all shipped items. It will not be possible to get all order-items regardless of status (open/shipped). The resource URI could the be like this sales/order-items?orderstatus={OPEN/SHIPPED} (the orderstatus query parameter would be mandatory then) or it could be two resources like this sales/order-items/open and sales/order-items/shipped. What is the preferred?
A resource is 'any information that can be named'. Your URIs should be entity based. 'order-items' is not an entity, but a data type.
/sales/order/order-1456321 is the Entity you most likely want. Which would contain the data of all order items.
If you wish to restrict access, you can return a client error if no query string is supplied. and having
/sales/order/order-12345?status=open
etc. Hope this helps.
EDIT:
/sales/order-items or /sales/orders/order-items?
This is domain specific, and really should be answered by a domain expert. Your URI Hierarchy provides scope (and so detail) to your resource. So as an educated guess, It does not make sense to have "order-items" within the scope of "/sales/orders/" because "order-items" is not an "order".
/sales/ordered-items
seems the most sensible answer.
On a personal note, and not to question your domain too much, Having a strong understanding of the flow of the business and information that's stored may result in something along the lines of these suggestions;
/sales/orders?status=open - Are all orders shipped at once?
/sales/orders/order-1234/packages?status=open - Are orders split into packages?
I'm currently designing an API and I came a cross a little problem:
How should a URL of a RESTful API look like when you should be able to identify an item by either an ID or a slug?
I could think of three options:
GET /items/<id>
GET /items/<slug>
This requires that the slug and the ID are distinguishable, which is not necessarily given in this case. I can't think of a clean solution for this problem, except you do something like this:
GET /items/id/<id>
GET /items/slug/<slug>
This would work fine, however this is not the only place I want to identify items by either a slug or an ID and it would soon get very ugly when one wants to implement the same approach for the other actions. It's just not very extendable, which leads us to this approach:
GET /items?id=<id>
GET /items?slug=<slug>
This seems to be a good solution, but I don't know if it is what one would expect and thus it could lead to frustrating errors due to incorrect use. Also, it's not so easy - or let's say clean - to implement the routing for this one. However, it would be easily extendable and would look very similar to the method for getting multiple items:
GET /items?ids=<id:1>,<id:2>,<id:3>
GET /items?slugs=<slug:1>,<slug:2>,<slug:3>
But this has also a downside: What if someone wants to identify some of the items he want to fetch with IDs, but the others with a slug? Mixing these identifiers wouldn't be easy to achieve with this.
What is the best and most widely-accepted solution for these problems?
In general, what matters while designing such an API?
Of the three I prefer the third option, it's not uncommon to see that syntax; e.g. parts of Twitter's API allow that syntax:
https://dev.twitter.com/rest/reference/get/statuses/show/id
A fourth option is a hybrid approach, where you pick one (say, ID) as the typical access method for single items, but also allow queries based on the slug. E.g.:
GET /items/<id>
GET /items?slug=<slug>
GET /items?id=<id>
Your routing will obvious map /items/id to /items?id=
Extensible to multiple ids/slugs, but still meets the REST paradigm of matching URIs to the underlying data model.
Can someone explain to me in, in REST terms, Twitter's design decision with the parameter placement in these two calls? It seems that the :id placement is inconsistent and arbitrary (although clearly this was deliberate).
GET statuses/:id/retweeted_by
Show user objects of up to 100 members who retweeted the status.
GET statuses/retweets/:id
Returns up to 100 of the first retweets of a given tweet.
There are other similar examples throughout their API (https://dev.twitter.com/docs/api), so I'm definitely missing something.
Thanks!
Just making guesses here
Someone at Twitter once pointed out that the Twitter API runs on several servlets. I can only assume that this was related - it's easier to map /retweets/* than to map every single combination.
Update: I think that the history of the API itself can also be relevant. Twitter's API hasn't really changed much over the past years, and if it did change then it would be because new features would be added. An endpoint like GET statuses/show/:id is old, while GET statuses/retweets/:id is newer. If Twitter at some point decided to change naming conventions, they couldn't just rename the old ones, since it would break applications.
Another theory of mine is that GET statuses/retweets/:id actually doesn't refer to the Tweet :id itself, but is about the tweets that were based on it. GET statuses/:id/retweeted_by is directly related to the tweet itself, by returning users and not other statuses.
I too am often puzzled by the naming consistency. I'm sure they have their reasons though.
I ended up checking with a friend at Twitter, who says:
"I just talked with the guy who originally wrote those two API
endpoints, and he doesn't remember why. To answer your question,
though, there probably isn't a good RESTful reason for that design."