At work here, we have a box serving XML feeds to business partners. Requests for our feeds are customized by specifying query string parameters and values. Some of these parameters are required, but many are not.
For example, we've require all requests to specify a GUID to identify the partner, and a request can either be for a "get latest" or "search" action:
For a search: http://services.null.ext/?id=[GUID]&q=[Search Keywords]
Latest data in category: http://services.null.ext/?id=[GUID]&category=[ID]
Structuring a RESTful URL scheme for these parameters is easy:
Search: http://services.null.ext/[GUID]/search/[Keywords]
Latest: http://services.null.ext/[GUID]/latest/category/[ID]
But what how should we handle the dozen or so optional parameters we have? Many of these are mutually exclusively, and many are required in combinations. Very quickly, the number of possible paths becomes overwhelmingly complex.
What are some recommended practices for how to map URLs with complex query strings to friendlier /REST/ful/paths?
(I'm interested in conventions, schemes, patterns, etc. Not specific technologies to implement URL-rewriting on a web server or in a framework.)
You should leave optional query parameters in the Query string. There is no "rule" in REST that says there cannot be a query string. Actually, it's quite the opposite. The query string should be used to alter the view of the representation you are transferring back to the client.
Stick to "Entities with Representable State" for your URL path components. Category seems OK, but what exactly is it that you are feeding over XML? Posts? Catalog Items? Parts?
I think a much better REST taxonomy would look like this (assuming the content of your XML feed is an "article"):
http://myhost.com/PARTNERGUID/articles/latest?criteria1=value1&criteria2=value2
http://myhost.com/PARTNERGUID/articles/search?criteria1=value1&criteria2=value2
If you're not thinking about the entities you are representing while building your REST structure, you're not doing REST. You're doing something else.
Take a look at this article on REST best practices. It's old, but it may help.
Parameters with values? One option is the query string. Using it is not inherently non-restful. Another option is to use the semi-colon, Tim Berners-Lee talks about them and they might just fit the bill, allowing the URL to make sense, without having massively long paths.
Related
The title is probably poorly worded, but I'm trying my hand at creating a REST api with symfony. I've studied a few public api's to get a feel for it, and a common principle seems to be dealing with a single resource path at a time. However, the data I'm working with has a lot of levels (7-8), and each level is only guaranteed to be unique under its parent (the whole path makes a composite key).
In this structure, I'd like to get all children resources from all or several parents. I know about filtering data using the queryParam at the end of a URI, but it seems like specifying the parent id(s) as an array is better.
As an example, let's say I have companies in my database, which own routers, which delegate traffic for some number of devices. The REST URI to get all devices for a router might look like this:
/devices/company/:c_id/routers/:r_id/getdevices
but then the user has to crawl through all :r_id's to get all the devices for a company. Some suggestions I've seen all involve moving the :r_id out of the path and using it in the the query string:
/devices/company/:c_id/getdevices?router_id[]=1&router_id[]=2
I get it, but I wouldn't want to use it at that point.
Instead, what seems functionally better, yet philosophically questionable, is doing this:
/devices/company/:c_id/routers/:[r_ids]/getdevices
Where [r_ids] is a stringified array of ids that can be decoded into an array of integers/strings server-side. This also frees up the query-parameter string to focus on filtering devices by attributes (age, price, total traffic, status).
However, I am new to all of this and having trouble finding what is "standard". Is this a reasonable solution?
I'll add I've tested the array string out in Symfony and it works great. But I can't tell if it can become a vehicle for malicious queries since I intend on using Doctrine's DBAL - I'll take tips on that too (although it seems like a problem regardless for string id's)
However, I am new to all of this and having trouble finding what is "standard". Is this a reasonable solution?
TL;DR: yes, it's fine.
You would probably see an identifier like that described using a level 4 URI Template, with your list of identifiers encoded via a path segment expansion.
Your example template might look something like:
/devices/company{/c_id}/routers{/r_ids}/devices
And you would need to communicate to the template consumer that c_id is a company id, and r_ids is a list of router identifiers, or whatever.
You've seen simplified versions of this on the web: URI templates are generalizations of web forms that read information from input controls and encode the inputs into the query string.
When needing to create a URL that takes a finite set of parameters, where all of said parameters are semantically the same "level", what is the current consensus around the use of delimiters within URLs? Here's an example:
/myresource/thing1,thing2,thing3
/myresource/thing2,thing1
/myresource/thing1;thing2;thing3
/myresource/thing1;thing3
That is to say, the parameter here could be a single, a pair or a triple. They can be specified in any order because they are not a logical tree, and thing2 is not a subordinate resource of thing1, so doing something like this seems "wrong":
/myresources/thing1/thing2/thing3
This bothers me because it implies a tree-like relationship between the elements of the triple, and that is not the case (despite many HTTP frameworks seemingly pushing this, wrongly in my view). In addition, using a query string doesn't feel right as this is not a search operation, it is a known triple in a very finite space - there's nothing to query or search, so to speak.
I suppose the other option would be to make it a POST request and supply a body that details the parts of the triple being supplied. This doesn't give me warm fuzzies though, for some reason.
How have others handled this? Delimiters seem clean to me, and communicate the intended semantics of the resource, but i know there are folks would would take a different view, and I was looking to understand the experiences of others who've had similar use cases.
Since any value can be missing and values can appear in any order, How would you know which value is for which parameter (if that matters).
I would have used query string for GET, or in the payload for POST.
Use query parameters
/path/to/the/resource?key1=value1&key2=value2&key3=value3
or matrix parameters
/path/to/the/resource;key1=value1;key2=value2;key3=value3
Without a proper example, I'm not sure exactly about your needs.
However, a little known fact is that any HTTP parameter can have multiple values. It is the way to go when you have a set of objects (see GoogleMaps static API for an example).
/path/to/the/resource?things=thing1&things=thing2&things=thing3
Then you can use the same API for single, pairs, triples (and more).
For a while I was (wrongly) thinking that a RESTful API just exposed CRUD operation to persisted entities for a web application. When you code something up in "the real world" you soon find out that this is not enough. For example, a bank account transfer doesn't have to be a persisted entity. It could be a transient resource where you POST to /transfers/ and in the payload you specify the details:
{"accountToCredit":1234, "accountToDebit":5678, "amount":10}
Using POST here makes sense because it changes the state on the server ($10 moves from one account to another every time this POST occurs).
What should happen in the case where it doesn't affect the server? The simple first answer would be to use GET. For example, you want to get a list of savings and checking accounts that have less than $100. You would then call something like GET to /accounts/searchResults?minBalance=0&maxBalance=100. What happens though if your search parameter need to use complex objects that wouldn't fit in the maximum length of a GET request.
My first thought was to use POST, but after thinking about it some more it should probably be a PUT since it isn't changing the state of the server, but from my (limited) understanding I always though of PUT as updating a resource and POST as creating a resource (like creating this search results). So which should be used in this case?
I found the following links which provide some information but it wasn't clear to me what should be used in the different cases:
Transient REST Representations
How to design RESTful search/filtering?
RESTful URL design for search
I would agree with your approach, it seems reasonable to me to use GET when searching for resources, and as said in one of your provided links, the whole point of query strings is for doing things like search. I also agree that PUT fits better when you want to update some resource in an idempotent way (no matter how many times you hit the request, the result will be the same).
So generally, I would do it as you propose. Now, if you are limited by the maximum length of GET request, then you could use POST or PUT, passing your parameters in a JSON, in a URI like:
PUT /api/search
You could see this as a "search resource" where you send new parameters. I know it seems like a workaround and you may be worried that REST is about avoiding verbs in the URIs. Well, there are few cases that it's still acceptable and RESTful to use verbs, e.g. in cases where calculation or conversion is involved to generate the result (for more about this, check this reference).
PS. I think this workaround is still RESTful, but even if it wasn't, REST isn't an obsession and an ultimate goal. Being pragmatic and keeping a clean API design might be a better approach, even if in few cases you are not RESTful.
When i have a resource, let's say customers/3 which returns the customer object and i want to return this object with different fields, or some other changes (for example let's say i need to have include in customer object also his latest purchase (for the sake of speed i dont want to do 2 different queries)).
As i see it my options are:
customers/3/with-latest-purchase
customers/3?display=with-latest-purchase
In the first option there is distinct URI for the new representation, but is this REALLY needed? Also how do i tell the client that this URI exist?
In the second option there is GET parameter telling the server what kind of representation to return. The URI parameters can be explained through OPTIONS method and it is easier to tell client where to look for the data as all the representations are all in one place.
So my question is which of these is better (more RESTful) and/or is there some better way to do this that i do not know about?
I think what is best is to define atomic, indivisible service objects, e.g. customer and customer-latest-purchase, nice, clean, simple. Then if the client wants a customer with his latest purchases, they invoke both service calls, instead of jamming it all in one with funky parameters.
Different representations of an object is OK in Java through interfaces but I think it is a bad idea for REST because it compromises its simplicity.
There is a misconception that making query parameters look like file paths is more RESTful. The query portion of the address is included when determining a distinct URI so the second option is fine.
Is there much of a performance hit in including the latest purchase data in all customer GET requests? If not, the simplest thing would be to do that so there would neither be weird URL params or double requests. If getting the latest order is a significant hardship (which it probably shouldn't be) there is nothing wrong with adding a flag in the query string to include it.
Which is the best way (in performance and security) to send multiple parameters to a web page (on a different server), considering that the length of the parameters may vary because I'm sending a list of products, and the customer may have selected more than one product, so we need to send each product on the querystring to the other page.
For example (I'm on C#); I want to call a web page like this:
Simple Querystring: thepage.asp?Product=1&Name=Coffee&Value=1.99
Json: thepage.asp?{"Product":"1","Name":"Coffee","Value":"1.99"}
XML: thepage.aps?<xml><Products><product>1</product><name>Coffee</name><Value>1.99</Value></Products>
(Obviouly considering we can't send special characters via querystring, but I put them here for better understanding)
Which will be the better way (performance, security)?
Thanks in advance.
Based on your comment, you're limited to what the third-party site will accept - if all it will handle is query-strings, that's how you'll have to send it. If it will handle form posts, then you could look at submitting the information in the headers of a post, but that is going to take more work (you also haven't specified if you're building a WebRequest on the server side, or doing this through JavaScript on the client side).
All things considered, here are some general points:
There are various limits on the length of a query string (IE limits them to about 2083 characters, some servers or proxies may ignore parts over 1024 characters etc), while POST requests can be much larger.
If you are doing this client side, the user can see the query string parameters (which has the benefit that they can book mark them), while they can't (easily) see POST requests.
For greater security, if the third party server supports it, submit the request over SSL.
Special characters can easily be sent via the query string if you UrlEncode them first.
As to performance, it depends on the amount of processing you have to do to create the query strings over creating XML or JSON strings.
I would use the simple querystring approach, which you could write a utility to convert the request.querystring collection into a format that works better for you (XML, JSON, Dictionary, etc.), IMHO.
HTH.
You need to keep in mind that there is a limit to how long your query string can be, depending on which browser your users use. IE6 has a limit of 2053 characters for example. I would suggest you come up with a method to keep your query string as short as possible to avoid hitting this limit.
As far as security goes, there really isn't any security if you are passing around information in a query string. Anyone can modify that information and then send it. If security is a major concern, you should look into encrypting the information before adding it to the query string, or find a different method for sending it altogether.
Come on what is the question asked ? which is the better way . no one answer proper here. all are telling about limitations. but not about the remedy to solve it . let say i want to pass 100 parameters generates dynamically all are in huge length , can i use here POST() then? I don't thinks so, just consider, what should the remedy then?? may be pass collection object as parameter.