Say we want to send a list of client IDs to some endpoint. Should we use the name "client" or "clients" for the query? I think both cases have pros and cons, but is there some convention for this?
GET https://somedomain.com/some/endpoint?client(s)=1&client(s)=2
REST doesn't care what spelling you use for your resource identifiers. Any information encoded into the identifier is done at the discretion of the server and for its own exclusive use.
Part of the reason for this: as the server, you want to be able to change how you encode information into the URI to make it work better for your infrastructure.
For example, if you were working with an query string parsing library that could automatically handle list arguments, provided that they matched some particular pattern, then you would want to be able to take advantage of that.
So the spelling conventions for query parameters is a local choice; very similar to the way that the spellings of variable names in code is a local choice.
Related
The standard REST verb for returning a value GET can take different parameters to select what to "get". Often there is one that takes an id to get a single value, and often some sort of search criteria to get a list.
Is there a standard way to specify the filtering and sorting of the data that is being searched for? For example, if I have an invoice record I'd like to write a GET query that says "give me all invoices for customer 123, with total > $345 and return in descending order of date".
If I were writing this myself I'd have something like:
GET http://example.com/mydata?query="customer=123&&total>345.00"&order="date"
(Note I didn't urlencode the url for clarity, though obviously that is required in practice, but I hope you get what I mean.)
I can certainly write something for this, but I am wondering if there is a standardized way to do this?
Is there a standard way to specify the filtering and sorting of the data that is being searched for?
Not that I'm aware of.
Note that HTTP doesn't really have queries (yet); HTTP has resource identifiers.
We've got a standard for resource identifiers (RFC 3986) and a standard for URI templates (RFC 6570) that describes how to produce a range of identifiers via variable expansion.
But as far as I can tell there is no published "standard" that automatically transforms a URI into a SQL query.
It's possible that one of the "convention over configuration" frameworks (ex: Rails) might have something useful here, but I haven't found it.
A situation where I want a URL for list of values for a filter a URL for best match out of them to be returned.
Example data is as follows
/studentInformation?student=Albert&class=3&rollno=13&marks=24 will return 2 entries as no value is a value of interest to me
/studentInformation/bestMatch?student=Albert&class=3&rollno=13&marks=24 will return 1 value which is the best match i.e entry no 3 (limiting to 1 would not find the best match)
what is the right way to form the URL for best match?
REST doesn't have a standard for designing URI. It just says that every resource should have one.
On the web, we have a standard that describes the production rules for URI (RFC 3986) and a standard that describes URI Templates (RFC 6570), but neither of those get into the level of detail that you seem to be asking for.
And that's on purpose: URI on the web are a lot like variable names in a programming language; it's more generally useful to afford you the freedom to make local decisions about spelling conventions.
The machines don't care about semantic relationships between the spelling of the URI and the information of the resource, so you can choose any spelling that makes things better for people (where people here could be customers looking at the URI in their browser history, or pasting it into emails, or operators looking at URI in web logs, or writers trying to document your resource model, or even just the programmers trying to implement the API).
I want to ask what is the most RESTful way for queries, I have this existing API
/entities/users?skip=0&limit=100&queries={"$find":{"$minus":{"$find":{"username":"markzu"}}}}
Easily the first parts of the query, skip and limit are easily identifiable however I find the "queries" part quite confusing for others. What the query means is to
Find every User minus Find User entities with username 'markzu'
The reason it is defined this way is due to the internal database query behavior.
Meaning in the NoSQL database we use, the resource run two transactional queries, first is to find everything in the User table minus a find User with a username that was specified (similar to SQL) -- boolean operations. So in other words, the query means, "fetch every User except username 'markzu' "
What is the proper way to define this in RESTful way, based on standards?
What is the proper way to define this in RESTful way, based on standards?
REST doesn't care what spelling you use for resource identifiers, so long as your choice is consistent with the production rules defined in RFC 3986.
However, we do have a standard for URI Templates
A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion.
You are already aware of the most familiar form of URI template -- key-value pairs encoded in the query string.
?skip=0&limit=100&username=markzu
That's often a convenient choice, because HTML understands how to process forms into url encoded queries.
It doesn't look like you need any other parameters, you just need to be able this query from others. So a perfectly reasonable choice might be
/every-user-except?skip=0&limit=100&username=markzu
It may help to think "prepared statement", rather than "query".
The underlying details of the implementation really shouldn't enter into the calculation at all. Your REST API is a facade that makes your app look like an HTTP aware key value store.
I am trying to create an API for my Rest services and i am struggling with the design rules that i try to follow. In generally i am trying to follow (among others) these guidelines:
Don't use verbs in the URIs
Don't use query parameters when altering states
Use plural
Don't use camel case
Now, i have to model something like the following:
Get all departments of a company
Get a department of a company
Delete all deprtaments of a company
Delete a department of a company
I am trying something like this:
GET company/departments
GET company/departments/<depName>
DELETE company/departments
DELETE company/departments {body: department name}
The above, follows the guidelines that i have mentioned, but i really don't think that the resulted URIs are good. Especially the fourth, does a different job and has the same URI as the third.
This is a common problem for me, and i encounter it many times when i am designing REST services. The result is that i always break some designing principles to achieve what i want or make uglier URIs (for example: DELETE company/departments/department).
So the actual question is:
In my design, how can i delete a single department with a Restfull-like URI?
A URL consists of several parts:
http://example.com/company/departments/12345?arg1=this&arg2=that
http: is the scheme. //example.com is the host. /company/departments/12345 is the path, ?arg1=this&arg2=that is the query string, consisting of two parameters: arg1 and arg2. There's another aspect, called matrix arguments, which won't be discussed here.
When REST talks about URLs, it refers to the entire thing. Not parts of it. To REST the entire URL is treated as an opaque blob.
That means REST doesn't care about any particular part: the scheme, the host, the path, or the arguments.
ftp://127.0.0.1/E280F814-1524-41D5-8735-43D8414AE242 is a perfectly fine URL as far as REST is concerned.
So as far as REST is concerned, it doesn't give a rip what path you use in your URL or whether you use parameters or not.
That said, the recommendations against parameters in a URL is because sometimes, caches don't cache paramaterized URLs properly. Thus the preference for /company/department/12345 over /company/department?id=12345.
The 12345 in the path is not a parameter. Its the name of the resource. Just like starwars.mp4 above is not a parameter, nor is E280F814-1524-41D5-8735-43D8414AE242. They're just names. The only folks that actually care are people. The computer doesn't care, the internet doesn't care, REST doesn't care. To them, it's just all bits.
So it sounds like a simple miscommunication that you're fighting. Try not to stress over it too much. Too much weight is pressed on URL naming anyway, when it's the resources and their representations that actually matter.
A better design for RESTful URIs is to use an identifier for the resource. In this case the resource is the department.
So your URIs could be like the following:
GET company/departments
GET company/departments/<department-id>
DELETE company/departments
DELETE company/departments/<department-id>
For example...
DELETE company/departments/58491
By using an identifier, rather than the department name, this avoids spaces in your URIs, which is undesirable. By department name, i assume you meant the user friendly display name, such as "Human Capital Management."
I agree. You should use URL like below to delete a department. Such URL identify a department and can be used to execute HTTP operations on it. Don't provide the department id or name within the payload of the request.
DELETE company/departments/58491
The following link could give you some more details about designing a RESTful service: https://templth.wordpress.com/2014/12/15/designing-a-web-api/.
Hope it helps you,
Thierry
I'm doing some research to help me develop a REST API and this is one topic I haven't seen discussed in depth anywhere.
If I have a user in the system, is it better to identify the user using a numeric identifier
/users/1
Or using a string identifier?
/users/RSmith
I can see hypothetical potential pros and cons to each approach, string identifiers are more human readable, less discoverable (can't be incremented to find valid users), and don't require storing another numeric id in the database (I wouldn't want to expose database ids through the API). Numeric identifiers have no inherent meaning and due to that, can be guaranteed to be immutable, whereas with a string id the user might want to rename the resource, thus changing the resource URI.
Is there a REST best practice here or does the best approach vary to system to system? If the latter, are there any additional pros and cons associated with each method?
As you know, strictly speaking, there is no advantage between both approaches. Yes, string identifies may be easier for people to remember, but apart from that, REST does not enforce "pretty" URLs (or IDs), because most of the time URLs are accessed by programs following the hyperlinks.
Thus, human friendly URLs should only be used for bootstrapping resources that may be remembered by humans. Also, ID guessing should not be a problem because either:
You have to restrict access to URLs based on any authentication method, or:
You have to use randomized/unguessable URLs that are not "public".
So which one to use? Most of the time, it does not matter, as IDs are not accessed directly. If you have to ensure people remember their URLs for some reason, try to do them human-friendly, but try to avoid resource-name change and apply some other means of authentication so that even guessed URLs don't get access to unauthorized places.
Only advantage of this: /users/RSmith is that it's more human friendly. From RESTfull perspective it doesn't matter because both are valid resource identifiers. Everything else depends on your system requrements.