It is straightforward to put resource id into url if it is a int or long type. e.g.
GET files/123
But my problem is that my resource identifier is a path. e.g. /folder_1/folder_2/a.sh because the underlying implementation is a filesystem. So I can not put it as part of rest api url because it is conflict with url path.
Here's approaches what I can think of:
Put the path id as the request param. e.g.
GET files?path=/folder_1/folder_2/a.sh
Encode/decode the path to make it qualifier as part of url.
Introduce another int/long id for this resource in backend. And map it to the path. The int/long type resource id is stored in database. And I need to maintain the mapping for each CURD operation.
I am not sure whether approach 1 is restful, approach 2 needs extra encoding/decoding, and approach 3 needs extra work to maintain the mapping.
I wonder what is the best practice to design the rest api url for this kind of case.
Simple:
#GET
#Path("/files/{path:.+}")
#Produces({MediaType.TEXT_PLAIN})
public String files(
#PathParam("path") String path
) {
return path;
}
When you query files/test1/tes2 via url output is:
test1/tes2
Just put the path after a prefix, for example:
GET /files/folder_1/folder_2/a.sh
There isn't a conflict, since when the request path starts with your known prefix (/files/, in the above example), you know that the rest should be parsed as the path to the file, including any slashes.
Well, my experience designing "restful" APIs shows that you have to take into consideration future extensions of your API.
So, the guidelines work best when followed closely when it makes sense.
In your specific example, the path of the file is more of an attribute of the file, that can also serve as its unique ID.
From your API client's perspective, /files/123 would make perfect sense, but /files/dir1/file2.txt is debatable.
A query parameter here would probably help more, much like what you would do if you wanted to retrieve a filtered list of files, rather than the whole collection.
On the other hand, using a query parameter would also help for future extensions, since supporting /files/{path} would also mean conflicts when attempting to add sub-resources to your files endpoint.
For example, let's assume that you might need in the future another endpoint /files/attributes. But, having such an endpoint, would exclude any possibility for your clients to match a file named attributes.
Related
I'm wondering what is the best way for my rest api uri name to include the module name that the ressource belongs to? lets clarify this, my rest api should expose the details of Object-A and should also expose the details of Object-B, in this case i can't use the ressource name ipAdresse:port/details because there is two details types.
add to this that i should not use the nesting style like this ipAdresse:port/objectA/:id/details.
So in this case, is it better to do it the following way (include the parent ressource or module name in the url):
ipAdresse:port/objecta/details
or this way (using hyphen):
ipAdresse:port/objectb-details
thanks
There's a small advantage to using path segments, if you have a family of these documents that want to link to each other
/objecta/details
/objecta/comments
/objecta/pricing
These resources can all reference each other using dot segments (ex: ../comments), which means that you don't have to specify the "objecta" part in the links. In other words, you could move the whole family of identifiers to a different location in your hierarchy, and relative resolution would just work.
/objectb-details
/objectb-comments
/objectb-pricing
Each of these paths is a single segment, so dot segments remove the entire path, which you would have to replace (ex: ../objectb-comment), and if you decide to replace the objectb prefix with something else, you also need to update all of the links.
In effect, using / gives you a little bit of future proofing.
That said, if the hyphen-minus is part of the name of the thing, then leave it in the identifier.
/objective-c/comments
If you bring one of these to me in a code review, I'm going to think you've lost the plot:
/objective/c/comments
/objective-c-comments
But of course they will work just as well (the machines don't care) as long as the identifiers match the syntax described by RFC 3986.
I'm creating a simple API which works with geographical data.
Some URLs look very simple like:
GET /towns/{id}
or
GET /towns
Now I want to get a town by alias, should I use this kind of URL?
GET /towns/alias/{alias}
What if I also want to get a list of towns located near certain town?
GET /towns/closest/{id}/radius/{radius}
I understand that my URLs can be any I want. What is a canonical way to do it?
I understand that my URLs can be any I want. What is a canonical way to do it?
There isn't really a "canonical way" to design URLs, any more than there is a canonical way to name variables -- there are only local spelling conventions.
RFC 3986 distinguishes between hierarchical and non-hierarchical data:
The path component contains data, usually organized in hierarchical form, that, along with data in the non-hierarchical query component (Section 3.4), serves to identify a resource within the scope of the URI's scheme and naming authority (if any)
The effect of using hierarchical data is that you can take advantage of dot-segments to compute one URI from another.
For example
/town/alias/{alias}
/alias/{alias}
Both of these spellings are "fine", but /town/alias gives us the option of using dot segments to specify an identifier under /town
/town/alias/abc + ../123
=> /town/alias/../123
=> /town/123
That can be handy when it allows you to re-use a representation for multiple resources in your hierarchy.
Yes it can possible through the URL routing.You can send any number of parameter through url.
Can you please confirm the technology you used?
Assume you have a REST service that already gets users by id, so the url looks something like
GET /users/{userId}
But you want to create a duplicate web service that gets users by email, so:
GET /users/{email}
Which is better?
Method 1:
Same method:
/users/{input}
...
if(isEmail(input)) queryByEmail(input);
else queryById(input);
Method 2:
Different Method:
GET /users/{userId}
GET /usersByEmail/{email}
Since there is no actual overlap between email addresses and IDs. I would just use same endpoint for both. Especially if GET /users/{id} is already a published interface.
So, I would go with 1st method.
GET /users/{identifier}
Then on the API server you have to add a small check, whether {identifier} is a number or not.
I would also like to note, that "pretty URLs" do not make it REST :) You probably will want to watch this lecture: https://www.youtube.com/watch?v=pspy1H6A3FM
My personal preference would be,
GET /users/id/{id}
GET /users/email/{email}
But it all depends on what you the rest endpoints to look like.
Which is better?
REST doesn't care; from the perspective of the client, the URI is opaque. The clients concerns are following links/submitting forms/completing templates.
Information encoded into the URI is done at the server's discretion and for its own exclusive use.
So you can use any spelling you like. As a rule, it's a good idea to conform to local spelling conventions (in much the same way that your variable names in code should conform to your coding conventions). But your clients shouldn't need to know the details of those conventions.
/users/{input}
...
if(isEmail(input)) queryByEmail(input);
else queryById(input);
Note that you aren't necessarily deeply committed to one approach; that's part of the point of decoupling the identifiers from the representations. For instance, your implementation could just as easily look like
/users/{input}
...
if(isEmail(input)) redirectTo(/users/email/{input});
else redirectTo(/users/id/{input});
which allows clients that have bookmarked the original URI to arrive at the correct resource.
We have REST API's. I was trying to figure out the best way to do a Get with some special characters.
Currently, we have something like this: http://myhost.com/api/book/name=HarryPotter
The above URL works just fine, but gets complicated when certain special character's are included in the queryparam like '&' or '/', which will result in "No operation matching request path ... is found, HTTP Method : GET, ContentType : /, Accept : /,"
for ex: http://myhost.com/api/book/name=Dark/Thirty.
This will consider the '/' in 'Dark/Thirty' as an URL separator.
What is the best practice to be able to search such queries. Is using a JSON a better practice, if yes should I be using a GET or a POST? I believe it should be POST, as any slash in the query param is treated as an Url separator.
Meaning: even this would fail for GET. http://myhost.com/api/book/search={"name"="Dark/Thirty"}
And since this is actually not a POST i do not want to use it. As I am just listing out the books that meet my search criteria and not modifying or adding anything.
Any guideline in tackling similar problems?
This link is a good read. In essence, if your Dark/Thirty is an identifier (i.e. uniquely identifies a resource), then modify it (in a predictable pattern) so that it does not have the special characters; e.g., DarkThirty or dark-thirty. If it is, however, a search term, then you would be better served not to make it RESTful, but just pass it as a normal parameter; that's what they're for.
The difference between GET and POST is not what characters are in it, but what the objective is. GET is for getting stuff: it should be free of side effects. A search, or retrieval of a page should be a GET. POST effects changes to a server. It is improbable you would need to make an operation that both requires sending more data than URL allows, and at the same time makes no changes on the server but simply renders a new page (allowing for exceptions like Shazam or TinEye).
Dealing with special characters in GET parameters is the job of URL encoding; if you have http://myhost.com/api/search?q=Dark%FThirty for a search, your site is no less good. There are two primary drivers for REST, as I understand them: human-friendliness and SEO-friendliness. Search does not need to be either. REST exists to identify resources, in my understanding; and search results from a query are not a resource.
To summarise, I'd go with:
http://myhost.com/api/book/dark-thirty (the resource is the book)
http://myhost.com/api/search?q=Dark%FThirty (the resource is the search procedure, with arguments)
URL encoding sounds like the easiest thing to do in your case, particularly since you already have a URL structure set up for your application that looks like http://myhost.com/api/book/name={internal-identifier} where internal-identifier resolves to your book name (encoded, of course).
From the REST perspective, it doesn't particularly matter whether the URL represents a query that can return a collection of resource representations or uniquely identifies a specific resource. You can use this structure for both.
Assume I have tree-like data, e.g. “files” and “folders”, basic operations are “list folder”, “create folder”, “rename”, “create file”, “fetch file”.
So how can I construct URIs for RESTful service? I've tried a few times but all solutions look not very nice to me.
For example, if I have “folder” resource referenced by URI `http://example.com/rest/here_path_to_folder, how can I list folder items? Fetch “file” from this folder?
I've seen Amazon AWS docs, they are using not very clean approach—passing “folder” path and folders delimiter as query arguments, this could cause ambiguity because different URIs will reference the same resource. Also I've tried appending keywords to the end of path, so listing “files” looked like:
GET /rest/path/to/folder:list HTTP/1.1
Rename:
POST /rest/path/to/folder:rename?target=NEW_NAME HTTP/1.1
But it still look terrible for me. So do you know any success stories of using 100% REST on hierarchial data?
I think it should be quite simple to use URIs to represent your hierarchical data structure. Although URIs don't strictly imply hierarchy (some people like to keep then completely opaque), meaningful URIs do have a naturally hierarchical feel and they should map nicely to your file/folder example.
In a RESTful system, resources have a common interface which (in your case) is defined by the HTTP verbs. The URI identifies a resource, REST dictates that it shouldn't be used to indicate the operation you are trying to perform.
So instead of
GET /rest/path/to/folder:list HTTP/1.1
I'd propose that to list the contents of a folder (find out it's state) you simply use:
GET /rest/path/to/folder HTTP/1.1
This should return a list of URIs which represent the files and subfolders that this folder contains. Then to get the contents of one of the files, I might then invoke:
GET /rest/path/to/folder/myfile HTTP/1.1
Renaming is a bit more tricky. In some cases a DELETE followed by a PUT would work, but I'm guessing you want to retain the folder contents without having to re-upload. One option is a PUT where the body contains a new folder path, which responds with a 204 and the Location header value pointing to the newly created folder (as described in 'Renaming a tag' here). Optional: If you want to be really friendly to your users, you could also return a 301 status (Moved permanently) with a link to the new URI if the anyone makes a request to the old URI.
Remember the path is just one of the properties that makes up the state of a folder, you can update that state with PUT without needing to introduce a custom 'rename' operation. In your case, you happen to use the path to decide your URI, but it's perfectly valid for a state change to cause a change in the URI.