I'm developing api documentation for a RESTful search API using Api Blueprint. I would like to be able to pass filters to the API so I can assemble:
filter[filtername1]=filtervalue1
filter[filtername2]=filtervalue2
Per this question, I'm using percent encoded square brackets, but unlike this question, it's not possible for us to describe every possible key name:
How to format hash-based parameters in the URL when creating Blueprint API doc?
I want the key name to be variable, since it could be any field in the source data. Does this work?
## Key-Value-Test [/api/v1/keyvaluetest?term={term}&filter%5B{field_name}%5D={field_value}]
+ term
+ filter_field
+ filter_value
Is there a recommended format for a two-dimensional array like this? It doesn't seem like this would work in Dredd because + filter_field doesn't really match filter[filter_field]
I am afraid that API Blueprint and Apiary does not yet allow these kind of dynamic URL definitions.
API Blueprint and Apiary only allows URI Templates as defined in RFC 6570
The following URI Template is not valid according to that RFC
GET /resource?year={year}&month={month}
You can change the URL to define something like the following:
## Key-Value-Test [/api/v1/keyvaluetest{?term,field_name,field_value}]
+ Parameters
+ term: a
+ field_name: b
+ field_value: c
There are two caveats with this method:
You can only give one field name and field value for the parameters. If you want more field parameters, you have to extend the URL.
You have to change the API url which I don't think you would want to.
Please start a feature request at http://support.apiary.io if you have any.
API Blueprint uses URI Templates standard. There are ways to express and expand arrays (see section 3.2.1), however, it expects "standard URI approach", meaning the URI would be expanded as follows:
/api/v1/keyvaluetest?term=yourterm&filter=filtervalue1&filter=filtervalue2
which is a "standard" way of doing arrays, except the most popular web language popularised your way back in 2000s.
The templates are designed for expansion: give it a bunch of variables and a string, and you'll get a properly-formatted string. As far as I am aware, there is no "wild match" (inserting pattern-match variables at a certain position in string).
The only solution I can think of within the realm of URL templates would be taking advantage of explosion modifier (see composite values):
/api/v1/keyvaluetest{?keys*}
which, given associative array of values [(filter%5Bfiltername1%5D, filtervalue1), (filter%5Bfiltername2%5D, filtervalue2) ] should expand properly.
However, I am not sure how to specify those in MSON as I don't think there is a support for "dynamic keys" and I think most of the tooling wouldn't handle it (yet).
Might be worth asking.
Related
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.
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?
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.
I'm wondering where to put the edit, and new keywords by rest application. I'll use express-resource in a project, and the default settings are these:
GET /forums -> index
GET /forums/new -> new
POST /forums -> create
GET /forums/:forum -> show
GET /forums/:forum/edit -> edit
PUT /forums/:forum -> update
DELETE /forums/:forum -> destroy
There is a problem with this solution: there is not a real resource behind the new and edit. I mean the URL-s refer to resources, and after any slash is a sub-resource.
For example:http://my.example.com/users/1 represents:
var firstUser = {
name: "John Smith",
birthDate: new Date(1952,10,4),
hobbies: ["skiing", "football"],
...
}
And http://my.example.com/users/1/birthDate represents:
firstUser.birthDate
But by http://my.example.com/users/1/edit there is no such property:
firstUser.edit
So something is wrong with this conception.
Where is the real place of these keywords? In queryString or in headers?
From the perspective of a REST API these do not exist anywhere as they are not related to the representation of resources. They are actions upon resources and therefore expressed by the HTTP methods used. They would not bee needed if you were to create an external client that uses the API.
There is likely a need to provide some support for this type of functionality so that something like a UI could be presented, but that is the concern of the particular application and not the API itself. At that point it becomes discretionary but I would certainly avoid using headers as that would be pretty outside of conventional practice. But by headers it appears that you actually meant URI path. Out of those 2 I would say the path is the better option since it clearly defines any type of UI as a distinct resource and would keep it apart from the clean API, while using a query string on a part of the API would more tightly (mistakenly) associate it with the underlying resource.
Some update after a year or so:
edit and new should be hyperlinks
these links are just the representations of possible operation calls
by following them it is possible to manipulate the resource they belong by sending representations of the intended resource state, and/or by calling the proper methods
these terms are no resources, they don't have their own URL (resource identifier)
Thanks the advices Matt Whipple!
I think the best way to learn REST is reading the Fielding dissertation. There are many tutorials out there, but the authors of most of these does not really understand REST.
I've inherited an iPhone app that has a file containing all code necessary to perform API calls to our server (ServerRequests.h/m).
All endpoints for the API are buried within the various methods, and I'm looking for a way to refactor these endpoints out into their own separate file, or at the very least declared constants at the top of this file.
The problem is portions of the API endpoints are variable, such as user_id, photo_id, etc.
Am I amble to store a format string as constant and then have the variable portions replaced at a later time?
If not, do you have any suggestions about how to manage my API endpoints in a better way than just strewing them all throughout a file?
Thanks!
If I understand your need, something like this might work for you:
#define SOME_ENDPOINT #"what/ever/%#/you/need"
At the point of use, you use string formatting to get the final string:
[NSString stringWithFormat:SOME_ENDPOINT, user_id, ...];
IOW the majority of the string is stored in a constant that is a template used as the format spec for formatting the final string.
Is that what you want? Or need something 'fancier'? There is a feature of Python that I miss in Obj-C - you can have 'named' specifiers in the format like #"some/%(user_id)s/etc/etc/" and when you perform the formatting, you supply a dict(ionary). The 'user_id' spec is used as a key to find the associated value, which is then formatted (e.g., using the 's' spec in my example. Have not found a similar feature in Obj-C tho.