So I have a theoretical question based on a lot of research that I have done recently with regards to REST API interfaces.
Firstly I understand that in REST, resources should be nouns and not verbs and each resource should be decoupled from the next resource, however the resources can return the same entities or collection of entities, depending on the purpose of the resource.
My focus however is performing restful search.
In all the research I have done, the most common solution I have come across is the use of parameters in the URL
api.test.com/search-cars?param1=val1¶m2=val2
Now while this is standard practice and is not truly breaking the rules of REST, why is it that no one represents the search parameters as an id (possibly in the form of JSON)
api.test.com/cars/{"color":"blue","year":"2013","make":"toyota"}
If I look at cars as a resource and represent my id as a JSON, I could easily say that I truly have a finite number of cars thus a finite and unique number of id's.
Further more this promotes pure rest by conforming to "resource/id"
What are the benefits and downsides to using parameters as in the first example?
What are the benefits and downsides to using JSON as an id with the "filters" as in the second example?
All your comments would be really helpful as I need to take a final decision on how to move forward with the first resource of my API. Also, I need to have a strong argument for my boss explaining why I decided on either of the methods.
The general form of an URL is
scheme://domain:port/path?query_string#fragment_id
So you propose two URLs:
search by query_string
search by last path segment
Search by query_string
I recommend to name the collection cars, not search-cars. As you write in your question, URLs identify resources. The cars resource identifies the collection of all cars. I have no idea what collection a resource called search-cars would identify.
GET http://api.test.com/cars
would return the collection of all cars.
GET http://api.test.com/cars/123
would return the car identified by 123.
GET http://api.test.com/cars?color=blue&year=2013
would return the collection of all blue cars build in 2013.
Search by path
Your second URL
GET http://api.test.com/cars/{"color":"blue","year":"2013","make":"toyota"}
would make the query (JSON) a part of the path. To make the two examples equal, I suppose to make the JSON a query parameter:
GET http://api.test.com/cars?search={"color":"blue","year":"2013","make":"toyota"}
JSON vs. named query parameters
Most REST frameworks support mapping of query params to method parameters.
Most REST frameworks allow you to map a path segment to a method parameter. And, again, most REST frameworks allow you to map JSON to an object or a simple dictionary.
What makes JSON harder to use is the need to escape the "{} characters:
{"color":"blue","year":"2013","make":"toyota"}
becomes
%7B%22color%22%3A%22blue%22%2C%22year%22%3A%222013%22%2C%22make%22%3A%22toyota%22%7D
which is not very nice.
Summary
You can use both the query_string and the path of the URL to identify a resource. Search parameters are better placed in the query_string because the ? can mentally be translated to the WHERE of SQL.
Don't use JSON in URLs because escaped JSON is hard to read.
Related
A REST API can have arguments in several places:
In the request body - As part of a json body, or other MIME type
In the query string - e.g. /api/resource?p1=v1&p2=v2
As part of the URL-path - e.g. /api/resource/v1/v2
What are the best practices and considerations of choosing between 1 and 2 above?
2 vs 3 is covered here.
What are the best practices and considerations of choosing between 1
and 2 above?
Usually the content body is used for the data that is to be uploaded/downloaded to/from the server and the query parameters are used to specify the exact data requested. For example when you upload a file you specify the name, mime type, etc. in the body but when you fetch list of files you can use the query parameters to filter the list by some property of the files. In general, the query parameters are property of the query not the data.
Of course this is not a strict rule - you can implement it in whatever way you find more appropriate/working for you.
You might also want to check the wikipedia article about query string, especially the first two paragraphs.
I'll assume you are talking about POST/PUT requests. Semantically the request body should contain the data you are posting or patching.
The query string, as part of the URL (a URI), it's there to identify which resource you are posting or patching.
You asked for a best practices, following semantics are mine. Of course using your rules of thumb should work, specially if the web framework you use abstract this into parameters.
You most know:
Some web servers have limits on the length of the URI.
You can send parameters inside the request body with CURL.
Where you send the data shouldn't have effect on debugging.
The following are my rules of thumb...
When to use the body:
When the arguments don't have a flat key:value structure
If the values are not human readable, such as serialized binary data
When you have a very large number of arguments
When to use the query string:
When the arguments are such that you want to see them while debugging
When you want to be able to call them manually while developing the code e.g. with curl
When arguments are common across many web services
When you're already sending a different content-type such as application/octet-stream
Notice you can mix and match - put the the common ones, the ones that should be debugable in the query string, and throw all the rest in the json.
The reasoning I've always used is that because POST, PUT, and PATCH presumably have payloads containing information that customers might consider proprietary, the best practice is to put all payloads for those methods in the request body, and not in the URL parms, because it's very likely that somewhere, somehow, URL text is being logged by your web server and you don't want customer data getting splattered as plain text into your log filesystem.
That potential exposure via the URL isn't an issue for GET or DELETE or any of the other REST operations.
I have java library that runs webservices and these return a response in XML. The webservices all revolve around giving a list of details about items. Recently, changes were made to allow the services to return JSON by simply converting the XML to JSON. When looking at the responses, I saw they're not as easy to parse as I thought. For example, a webservice that returns details about items.
If there are no items, the returned JSON is as follows:
{"ItemResponse":""}
If there is 1 item, the response is as follows (now itemResponse has a object as value instead of a string):
{"ItemResponse":{"Items":{"Name":"Item1","Cost":"$5"}}}
If there two or more items, the response is (now items has an array as value instead of an object):
{"ItemResponse":{"Items":[{"Name":"Item1","Cost":"$5"},{"Name":"Item2","Cost":"$3"}]}}
To parse these you need several if/else which I think are clunky.
Would it be an improvement if the responses were:
0 items: []
1 item: [{"Name":"Item1","Cost":"$5"}]
2 items: [{"Name":"Item1","Cost":"$5"},{"Name":"Item2","Cost":"$3"}]
This way there is always an array, and it contains the itemdata. An extra wrapper object is possible:
0 items: {"Items":[]}
1 item: {"Items":[{"Name":"Item1","Cost":"$5"}]}
2 items: {"Items":[{"Name":"Item1","Cost":"$5"},{"Name":"Item2","Cost":"$3"}]}
I'm not experienced in JSON so my question is, if you were a developer having to use these webservices, how would you expect the JSON resonse to be formatted? Is it better to always return a consistent array, even if there are no items or is this usually not important? Or is an array not enough and do you really expect a wrapper object around the array?
What are conventions/standards regarding this?
Don't switch result types, always return an array if there are more items possible. Do not mix, for 1 item an object for more an array. That's not a good idea.
Another best practise is that you should version your API. Use something like yoursite.com/api/v1/endpoint. If you don't do this and you change the response of your API. All your client apps will break. So keep this in mind together with documentation. (I've seen this happen a lot in the past..)
As a developer I personally like your second approach, but again it's a preference. There is no standard for this.
There are several reasons to use json:
much more dense and compact: thus data sent is less
in javascript you can directly access those properties without parsing anything. this means you could convert it into an object read the attributes (often used for AJAX)
also in java you usually don't need to parse the json by yourself - there are several nice libs like www.json.org/java/index.html
if you need to know how json is build ... use google ... there tons of infos.
To your actual questions:
for webservices you often could choose between xml and json as a "consumer" try:
https://maps.googleapis.com/maps/api/place/textsearch/json
and
https://maps.googleapis.com/maps/api/place/textsearch/xml
there is no need to format json visually - is it not meant for reading like xml
if your response doesn't have a result, json-service often still is giving a response text - look again at the upper google map links - those are including a response status which makes sense as it is a service.
Nevertheless it's the question if it is worth converting from xml to json if there isn't a specific requirement. As Dieter mentioned: it depends on who is already using this service and how they are consumed ... which means the surrounding environment is very important.
What are REST resources and how do they relate to resource names and resource representations?
I read a few articles on the subject, but they were too abstract and they left me more confused than I was before.
Is the following URL a resource? If it is, what is the name of that resource and what is its representation?
http://api.example.com/users.json?length=2&offset=5
The GET response of the URL should look something like:
[
{
id: 6,
name: "John"
},
{
id: 7,
name: "Jane"
}
]
The reason why articles on REST resources are abstract is because the concept of a REST resource is abstract. It's basically "whatever thing is accessed by the URL you supply". So, in your example, the resource would be the list of two users starting at offset 5 in some bigger list. Note that, how the resource is implemented is a detail you don't care about unless you are the one writing the implementation.
Is the following URL a resource?
The URL is not a resource, it is a label that identifies the resource, it is, if you like, the name of the resource.
The JSON is a representation of the resource.
What’s a Resource?
A resource is anything that’s important enough to be referenced as a
thing in itself. If your users might “want to create a hypertext link
to it, make or refute assertions about it, retrieve or cache a
representation of it, include all or part of it by reference into
another representation, annotate it, or perform other operations on
it”, then you should make it a resource.
Usually, a resource is something that can be stored on a computer and
represented as a stream of bits: a document, a row in a database, or
the result of running an algorithm. A resource may be a physical
object like an apple, or an abstract concept like courage, but (as
we’ll see later) the representations of such resources are bound to be
disappointing. Here are some possible resources:
Version 1.0.3 of the software release
The latest version of the software release
The first weblog entry for October 24, 2006
A road map of Little Rock, Arkansas
Some information about jellyfish
A directory of resources pertaining to jellyfish
The next prime number after 1024
The next five prime numbers after 1024
The sales numbers for Q42004
The relationship between two acquaintances, Alice and Bob
A list of the open bugs in the bug database
The text is from the O'Reilly book "RESTful Web Services".
The URL is never a resource or its name or its representation.
URL just tells where the resource is located and You can invoke GET,POST,PUT,DELETE etc on this URL to invoke the resource.
Data responded back are the resources while the form of the data is its representation.
Let's say Your URL with given GET parameters can output a JSON resource - this is the JSON representation of this resource. While with other flag in the GET it could respond with the same data in XML - that will be another representation of the very same resource.
EDIT: Due to the comments to the OP and to my answer I'm adding another explanations.
Also the resource name is considered to be the 'script name', e.g. in this case it is users.json while this resource name is self describing the resource representation itself - when calling this resource we expect the resource is in JSON, while when calling e.g. users.xml we would expect the data in XML.
When I change the offset parameter in GET the response contains
different data set - is it a new resource or its representation?
When I define which columns are returned in response in GET, is it a different resource or different representation, or?
Well, here the problem and answer are clear - we still call the same URL, the server responses with the data in the same form (still it is JSON), data still contains information about users - just the information itself has changed due to the new offset parameter. So it is obvious that it is still the same resource with the same representation and the same resource name as before.
Second problem could be a little confusing. Though we are calling the same resource, though the resource contains the same data (just with only predefined column set) and though the data is in the same representation it could seem to us as a different resource. But due to the points in the paragraph above it is nor the different resource or different representation. Though the data set contains less information the requesting side (filtering this data set) should be considering this and behave accordingly. So again: it is the same resource with the same resource name and the same resource representation.
REST
This architectural style was defined in the chapter 5 of Roy T. Fielding's dissertation.
REST is about resource state manipulation through their representations on the top of stateless communication between client and server. It's a protocol independent architectural style but, in practice, it's commonly implemented on the top of the HTTP protocol.
Resources
The resource itself is an abstraction and, in the words of the author, a resource can be any information that can be named. The domain entities of an application (e.g. a person, a user, a invoice, a collection of invoices, etc) can be resources. See the following quote from Fielding's dissertation:
5.2.1.1 Resources and Resource Identifiers
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
More precisely, a resource R is a temporally varying membership function MR(t), which for time t maps to a set of entities, or values, which are equivalent. The values in the set may be resource representations and/or resource identifiers. [...]
Resource representations
A JSON document is resource representation that allows you to represent the state of a resource. A server can provide different representations for the same resource. For example, using XML and JSON documents. A client can use content negotiation to request different representations of the same resource.
Quoting Fielding's dissertation:
5.2.1.2 Representations
REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.
A representation consists of data, metadata describing the data, and, on occasion, metadata to describe the metadata (usually for the purpose of verifying message integrity). Metadata is in the form of name-value pairs, where the name corresponds to a standard that defines the value's structure and semantics. Response messages may include both representation metadata and resource metadata: information about the resource that is not specific to the supplied representation. [...]
Over HTTP, request and response headers can be used to exchange metadata about the representation.
Resource identifiers
A URL a resource identifier that identifies/locates a resource in the server.
This answer may also be insightful.
What are REST resources and how do they relate to resource names and resource representations?
REST doesn't mean a great deal more then you use HTTP verbs (GET, POST, PUT, DELETE, etc) properly.
Is the following URL a resource?
All URLs are strings that tell computers where a resource can be located. (Hence the name: Uniform Resource Locator).
A resource is:
a noun
that is unique
and can be represented as data
and has at least one URI
I go into more detail on my blog post, What, Exactly, Is a RESTful Resource?
Representational State Transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web. REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. Resources are a set of addressable objects, basically files and documents, linked using URLs. As correctly pointed out above by Quentin, REST archiecture simply implies that you'd use the HTTP verbs GET/POST/PUT/DELETE...
Conceptually you can think about a resource as everything which is accessible on the web using an URL.
If you stick to this rule http://api.example.com/users.json?length=2&offset=5 can be considered a resource
You've only provided what appear to be relative parameters rather than "ID" which is (or should be) concrete. Remember, get operations should be idempotent (i.e. repeatable with the same outcome).
What is REST?
REST is an architecture Style which stands for Representational(RE) State(S) transfer(T).
What is REST Resource ?
Rest Resource is data on which we want to perform operation(s).So this data can be present in database as record(s) of table(s) or in any other form.This record has unique identifier with which it can be identified like id for Employee.
Now when this data is requested by unique url like http://www.example.com/employees/123,so ultimately data or record which is present in database will be converted to JSON/XML/Plain text format by Rest Service and will be sent to Consumer.
So basically,what is happening here is REPRESENTATIONAL STATE TRANSFER, in a way that state of the data present in database is transferred to another format which can be JSON/XML or plain text.
So in this case 1 employee represents 1 resource which can be accessed by unique url like http://www.example.com/employees/123
In case we want to get list of all resources(employees),we will do:
http://www.example.com/employees
Hope this will help.
REST stands for REpresentational State Transfer. It's a method of transferring variable information from one location to another. A common method of doing this is using JSON - a way of formatting your variables so that they can be transferred without loss of information.
PHP, for example, has built in JSON support. Passing a PHP array to json_encode($array) will output a string in the format you posted (which by the way, is indeed a REST resource, because it gives you variables and information).
In PHP, the array you posted would turn out as:
Array (
[0]=>Array (
['id']=>6;
['name']=>'John';
)
[1]=>Array (
['id']=>7;
['name']=>'Jane';
)
)
I have a rest web service api, and I have a lot of stats that are aggregates of child data in an object. Where should I nest these stats? I thought about making them a resource all of their own, but it would mean a huge number of requests, instead of including them in a single json response.
For example:
GET /data
game:{
level: 1,
events:[
{event:...}
]
total_events: 23,
avg_events: 3
}
Or should things like total_events be within the events object?
I haven't found any good examples of how to this.
I'm not entirely sure I understand your intentions, but I would nevertheless put such aggregate information in the parent resource, along with the listing of child URLs.
If the child link list is too much trouble to build and the client is often only interested in the statistics, then you could introduce an extra query parameter to switch between the available respresentation formats. (e.g. "stats_only", "links", or "full".)
What naming convention is recommended when writing an MVC app that has both front-end and JSON paths to the required data?
For example, let's say the user of your site has "Things". They should be able to go to a page to view their things, but we also need a way to pull those things back as JSON on other pages. I've been able to think of several options but I'm not keen enough on any of them to proceed. Here's what I've got:
/things/list for UI, /json/things for JSON - this would require a JsonController which would end up serving different kinds of objects, thereby defeating any chance of entity separation before we even start.
/things/list for UI, /things/list/json for JSON - probably my preferred option at the moment, but requires magic stringing (albeit just "json"). Also, if you also need a (string id) action signature for taking in some filter parameters or such, then you have the choice of adding an extra route or doing some dirty string splitting.
/account/mythings for UI, /things/list for JSON - a bit cleaner, but there might not always be a relevant controller that you could serve the "things" from. Plus, you're mixing entities again.
All and any suggestions welcome, thanks!
Arguably the path names could all be the same. You can examine the Accept header for the mime-type of your client's desired response, and then return an appropriate view based on what you find there:
application/json: JSON View
text/xml: XML View
text/plain, text/html: JSP
View
Browsers set this field to HTML; your JSON clients would simply set this field as appropriate.
It's highly unlikely that anyone would be bookmarking a URL that requests JSON so I think that it's not that important to keep the URL as clean. It's also likely to be programmatically generated, not hand entered. Given these, I'd consider adding it as a query parameter.
/things/list -- HTML
/things/list?format=json -- JSON
This won't break your URLs if you do have ID parameters or need other parameters as well. It could also work with POSTs as well as GETs.
/things/1 -- HTML for "thing 1"
/things/1?format=json -- JSON for "thing 1"
I use the convention of
/things/list -- HTML
/things/_listpage -- AJAX
The rule is that all AJAXed actions/views have a leading underscore. This tells me that they are never called top-level, and usually have no master page associated. In this case, I keep the action under the same controller in order to share any associated logic.
Typically in the list view I would have a
<% RenderAction("_listpage", "things", new {page = ViewData["CURRENT_PAGE"]}); %>
I would recommend a slight variation/elaboration to the suggestion by #RedFilter
/things/list -- HTML
/things/_list -- return HTML help and examples (more for you than them).
/things/_list/schema -- schema info
/things/_list/json -- JSON format
/things/_list/xml -- XML format
/things/_list/csv -- csv format
/things/_list/tab -- tab deliminated format
/things/_list/wdsl -- implemented soap web service
etc.. I feel it is more extensible. It looks scary, but it is easy to pass the data contents through a decorator based on the format requested making a whole host of file formats available with practically just a few lines of code.
Here is a crude conceptual example:
public ActionResult _list(string id)
{
string data = "";
DataTable oDataTable = this.oDAO.Get("list"); // pretend data retrieval
try{
if(!String.IsNullOrEmpty(id)){
data = this.oDecorator.FormatData(id,oDataTable);
this.ContentTypeChange(id); // change application handler
}else{
data = this.GetHelp("_list");
}
}catch{}
ViewData["data"] = data;
return View();
}
...help can be more of a feature list, technical examples, or whatever you want. Of course you can start with just having native JSON and add more data formats to your decorator as requirements grow which is nice. For many of my projects it starts as a pure json rest pull by an AJAX and tends to bloom into other formats that are needed based on site popularity, so I have found this robust enough to use in an enterprise setting for smaller projects that often grow big.