asp.net c# pdf to image : Convert word to fillable pdf form application software utility azure windows .net visual studio RESTful_Best_Practices-v1_11-part1828

RESTful Service Best Practices
Safety
From Wikipedia:
Some methods (for example, HEAD, GET, OPTIONS and TRACE) are defined as safe, 
which means they are intended only for information retrieval and should not change the 
state of the server. In other words, they should not have side effects, beyond relatively 
harmless effects such as logging, caching, the serving of banner advertisements or 
incrementing a web counter. Making arbitrary GET requests without regard to the context 
of the application's state should therefore be considered safe.
In short, safety means that calling the method does not cause side effects.  Consequently, clients can 
make safe requests repeatedly without worry of side effects on the server.  This means that services 
must adhere to the safety definitions of GET, HEAD, OPTIONS and TRACE operations.  Otherwise, 
besides being confusing to service consumers, it can cause problems for Web caching, search engines 
and other automated agents—making unintended changes on the server.
By definition, safe operations are idempotent, since they produce the same result on the server.
Safe methods are implemented as read-only operations.  However, safety does not mean that the server 
must return the same response every time.
HTTP Verbs
The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the 
action counterpart to the noun-based resource.  The primary or most-commonly-used HTTP verbs (or 
methods, as they are properly called) are POST, GET, PUT, and DELETE.  These correspond to create, 
read, update, and delete (or CRUD) operations, respectively.  There are a number of other verbs, too, 
but are utilized less frequently.  Of those less-frequent methods, OPTIONS and HEAD are used more 
often than others.
GET
The HTTP GET method is used to retrieve (or read) a representation of a resource.  In the “happy” (or 
non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 
(OK).  In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
Examples:
GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345/orders
GET http://www.example.com/buckets/sample
According to the design of the HTTP specification, GET (along with HEAD) requests are used only to 
read data and not change it.  Therefore, when used this way, they are considered safe.  That is, they can 
be called without risk of data modification or corruption—calling it once has the same effect as calling 
it 10 times, or none at all.  Additionally, GET (and HEAD) is idempotent, which means that making 
multiple identical requests ends up having the same result as a single request.
05/29/12
www.RestApiTutorial.com
Page 11 of 34
Convert word to fillable pdf form - C# PDF Form Data fill-in Library: auto fill-in PDF form data in C#.net, ASP.NET, MVC, WinForms, WPF
Online C# Tutorial to Automatically Fill in Field Data to PDF
convert word form to fillable pdf; create a pdf form to fill out
Convert word to fillable pdf form - VB.NET PDF Form Data fill-in library: auto fill-in PDF form data in vb.net, ASP.NET, MVC, WinForms, WPF
VB.NET PDF Form Data fill-in library: auto fill-in PDF form data in vb.net, ASP.NET, MVC, WinForms, WPF
convert pdf fillable form to word; pdf signature field
RESTful Service Best Practices
Do not expose unsafe operations via GET—it should never modify any resources on the server.
PUT
PUT is most-often utilized for update capabilities, PUT-ing to a known resource URI with the request 
request body containing the newly-updated representation of the original resource.
However, PUT can also be used to create a resource in the case where the resource ID is chosen by the 
client instead of by the server.  In other words, if the PUT is to a URI that contains the value of a non-
existent resource ID.  Again, the request body contains a resource representation.  Many feel this is 
convoluted and confusing.  Consequently, this method of creation should be used sparingly, if at all.
Alternatively, use POST to create new resources and provide the client-defined ID in the body 
representation—presumably to a URI that doesn't include the ID of the resource (see POST below).
Examples:
PUT http://www.example.com/customers/12345
PUT http://www.example.com/customers/12345/orders/98765
PUT http://www.example.com/buckets/secret_stuff
On successful update, return 200 (or 204 if not returning any content in the body) from a PUT.  If using 
PUT for create, return HTTP status 201 on successful creation.  A body in the response is optional—
providing one consumes more bandwidth.   It is not necessary to return a link via a Location header in 
the creation case since the client already set the resource ID.  See the Return Values section below.
PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent.  In 
other words, if you create or update a resource using PUT and then make that same call again, the 
resource is still there and still has the same state as it did with the first call.
If, for instance, calling PUT on a resource increments a counter within the resource, the call is no 
longer idempotent. Sometimes that happens and it may be enough to document that the call is not 
idempotent.  However, it's recommended to keep PUT requests idempotent.  It is strongly 
recommended to use POST for non-idempotent requests.
POST
The POST verb is most-often utilized for creation of new resources.  In particular, it's used to create 
subordinate resources.  That is, subordinate to some other (e.g. parent) resource.  In other words, when 
creating a new resource, POST to the parent and the service takes care of associating the new resource 
with the parent, assigning an ID (new resource URI), etc.
Examples:
POST http://www.example.com/customers
POST http://www.example.com/customers/12345/orders
On successful creation, return HTTP status 201, returning a Location header with a link to the newly-
created resource with the 201 HTTP status.
POST is neither safe or idempotent.  It is therefore recommended for non-idempotent resource requests.  
Making two identical POST requests will most-likely result in two resources containing the same 
05/29/12
www.RestApiTutorial.com
Page 12 of 34
C# Create PDF from OpenOffice to convert odt, odp files to PDF in
advanced .NET control to change ODT, ODS, ODP forms to fillable PDF formats in using RasterEdge.XDoc.Word; How to Use C#.NET Demo Code to Convert ODT to PDF in
create a fillable pdf form from a pdf; convert pdf to pdf form fillable
C# Create PDF Library SDK to convert PDF from other file formats
Best C#.NET component to create searchable PDF document from Microsoft Office Word, Excel and PowerPoint. Create fillable PDF document with fields.
best pdf form filler; create a fillable pdf form in word
RESTful Service Best Practices
information.
PUT vs POST for Creation
In short, favor using POST for resource creation.  Otherwise, use PUT when the client is in charge of 
deciding which URI (via it's resource name or ID) the new resource will have:  if the client knows what 
the resulting URI (or resource ID) will be, use PUT at that URI.  Otherwise, use POST when the server 
or service is in charge of deciding the URI for the newly-created resource.  In other words, when the 
client doesn't (or shouldn't) know what the resulting URI will be before creation, use POST to create 
the new resource.
DELETE
DELETE is pretty easy to understand.  It is used to delete a resource identified by a URI.
Examples:
DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/buckets/sample
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the 
representation of the deleted item (often demands too much bandwidth), or a wrapped response (see 
Return Values below).  Either that or return HTTP status 204 (NO CONTENT) with no response body.  
In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the 
recommended responses.
HTTP-spec-wise, DELETE operations are idempotent.  If you DELETE a resource, it's removed.  
Repeatedly calling DELETE on that resource ends up the same: the resource is gone.  If calling 
DELETE say, decrements a counter (within the resource), the DELETE call is no longer idempotent.  
As mentioned previously, usage statistics and measurements may be updated while still considering the 
service idempotent as long as no resource data is changed.  Using POST for non-idempotent resource 
requests is recommended.
There is a caveat about DELETE idempotence, however.  Calling DELETE on a resource a second time 
will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer 
findable.  This makes DELETE operations no longer idempotent, but is an appropriate compromise if 
resources are removed from the database instead of being simply marked as deleted.
Below is a table summarizing recommended return values of the primary HTTP methods in 
combination with the resource URIs:
HTTP Verb
/customers
/customers/{id}
GET
200 (OK), list of customers. Use pagination, 
sorting and filtering to navigate big lists.
200 (OK), single customer. 404 (Not 
Found), if ID not found or invalid.
PUT
404 (Not Found), unless you want to 
update/replace every resource in the entire 
collection.
200 (OK) or 204 (No Content).  404 
(Not Found), if ID not found or 
invalid.
05/29/12
www.RestApiTutorial.com
Page 13 of 34
C# PDF Field Edit Library: insert, delete, update pdf form field
A professional PDF form creator supports to create fillable PDF form in C#.NET. An advanced PDF form maker allows users to create editable PDF form in C#.NET.
add attachment to pdf form; adding a signature to a pdf form
VB.NET Create PDF from OpenOffice to convert odt, odp files to PDF
VB.NET How-to, VB.NET PDF, VB.NET Word, VB.NET Excel, VB.NET Convert OpenOffice Spreadsheet data to PDF. Turn ODT, ODS, ODP forms into fillable PDF formats.
convert pdf into fillable form; convert pdf file to fillable form online
RESTful Service Best Practices
POST
201 (Created), 'Location' header with link to 
/customers/{id} containing new ID.
404 (Not Found).
DELETE
404 (Not Found), unless you want to delete the 
whole collection—not often desirable.
200 (OK).  404 (Not Found), if ID 
not found or invalid.
Resource Naming
In addition to utilizing the HTTP verbs appropriately, resource naming is arguably the most debated 
and most important concept to grasp when creating an understandable, easily leveraged Web service 
API.  When resources are named well, an API is intuitive and easy to use.  Done poorly, that same API 
can feel klutzy and be difficult to use and understand.  Below are a few tips to get you going when 
creating the resource URIs for your new API.
Essentially, a RESTFul API ends up being simply a collection of URIs, HTTP calls to those URIs and 
some JSON and/or XML representations of  resources, many of which will contain relational links.  
The RESTful principal of addressability is covered by the URIs.  Each resource has its own address or 
URI—every interesting piece of information the server can provide is exposed as a resource.  The 
constraint of uniform interface is partially addressed by the combination of URIs and HTTP verbs, and 
using them in line with the standards and conventions.
In deciding what resources are within your system, name them as nouns as opposed to verbs or actions.  
In other words, a RESTful URI should refer to a resource that is a thing instead of referring to an 
action.  Nouns have properties as verbs do not, just another distinguishing factor.
Some example resources are:
• Users of the system.
• Courses in which a student is enrolled.
• A user's timeline of posts.
• The users that follow another user.
• An article about horseback riding.
Each resource in a service suite will have at least one URI identifying it.  And it's best when that URI 
makes sense and adequately describes the resource.  URIs should follow a predictable, hierarchical 
structure to enhance understandability and, therefore, usability:  predictable in the sense that they're 
consistent, hierarchical in the sense that data has structure—relationships.  This is not a REST rule or 
constraint, but it enhances the API.
RESTful APIs are written for consumers.  The name and structure of URIs should convey meaning to 
those consumers.  It's often difficult to know what the data boundaries should be, but with 
understanding of your data, you most-likely are equipped to take a stab and what makes sense to return 
as a representation to your clients.  Design for your clients, not for your data.
Let's say we're describing an order system with customers, orders, line items, products, etc.  Consider 
the URIs involved in describing the resources in this service suite:
05/29/12
www.RestApiTutorial.com
Page 14 of 34
VB.NET Create PDF Library SDK to convert PDF from other file
Best VB.NET component to convert Microsoft Office Word, Excel and Create fillable PDF document with fields in Visual Basic .NET application.
create a fillable pdf form online; convert word form to pdf with fillable
VB.NET Create PDF from Word Library to convert docx, doc to PDF in
Create PDF files from both DOC and DOCX formats. Convert multiple pages Word to fillable and editable PDF documents.
create a fillable pdf form from a word document; convert pdf form fillable
RESTful Service Best Practices
Resource URI Examples
To insert (create) a new customer in the system, we might use:
POST http://www.example.com/customers
To read a customer with Customer ID# 33245:
GET http://www.example.com/customers/33245
The same URI would be used for PUT and DELETE, to update and delete, respectively.
Here are proposed URIs for products:
POST http://www.example.com/products
for creating a new product.
GET|PUT|DELETE http://www.example.com/products/66432
for reading, updating, deleting product 66432, respectively.
Now, here is where it gets fun...  What about creating a new order for a customer?
One option might be:
POST http://www.example.com/orders
And that could work to create an order, but it's arguably outside the context of a customer.
Because we want to create an order for a customer (note the relationship), this URI perhaps is not as 
intuitive as it could be.  It could be argued that the following URI would offer better clarity:
POST http://www.example.com/customers/33245/orders
Now we know we're creating an order for customer ID# 33245.
Now what would the following return?
GET http://www.example.com/customers/33245/orders
Probably a list of orders that customer #33245 has created or owns.  Note:  we may choose to not 
support DELETE or PUT for that url since it's operating on a collection.
Now, to continue the hierarchical concept, what about the following URI?
POST http://www.example.com/customers/33245/orders/8769/lineitems
That might add a line item to order #8769 (which is for customer #33245).  Right!  GET for that URI 
might return all the line items for that order.  However, if line items don't make sense only in customer 
context or also make sense outside the context of a customer, we would offer a POST 
www.example.com/orders/8769/lineitems URI.
Along those lines, because there may be multiple URIs for a given resource, we might also offer a GET 
http://www.example.com/orders/8769 URI that supports retrieving an order by number without having 
to know the customer number.
To go one layer deeper in the hierarchy:
GET http://www.example.com/customers/33245/orders/8769/lineitems/1
Might return only the first line item in that same order.
By now you can see how the hierarchy concept works.  There aren't any hard and fast rules, only make 
sure the imposed structure makes sense to consumers of your services.  As with everything in the craft 
of Software Development, naming is critical to success.
Look at some widely used APIs to get the hang of this and leverage the intuition of your teammates to 
05/29/12
www.RestApiTutorial.com
Page 15 of 34
C# Create PDF from Word Library to convert docx, doc to PDF in C#.
Convert multiple pages Word to fillable and editable PDF documents in both .NET WinForms and ASP.NET. Convert both DOC and DOCX formats to PDF files.
pdf fillable form creator; add fillable fields to pdf online
VB.NET Create PDF from PowerPoint Library to convert pptx, ppt to
VB.NET How-to, VB.NET PDF, VB.NET Word, VB.NET Excel, VB.NET PowerPoint, VB.NET Tiff, VB Convert multiple pages PowerPoint to fillable and editable
convert pdf fillable form to html; create pdf fill in form
RESTful Service Best Practices
refine your API resource URIs.  Some example APIs are:
• Twitter: https://dev.twitter.com/docs/api
• Facebook: http://developers.facebook.com/docs/reference/api/
• LinkedIn: https://developer.linkedin.com/apis
Resource Naming Anti-Patterns
While we've discussed some examples of appropriate resource names, sometimes it's informative to see 
some anti-patterns.  Below are some examples of poor RESTful resource URIs seen in the “wild.”  
These are examples of what not to do!
First up, often services use a single URI to specify the service interface, using query-string parameters 
to specify the requested operation and/or HTTP verb.  For example to update customer with ID 12345, 
the request for a JSON body might be:
GET http://api.example.com/services?op=update_customer&id=12345&format=json
By now, you're above doing this.  Even though the 'services' URL node is a noun, this URL is not self-
descriptive as the URI hierarchy is the same for all requests.  Plus, it uses GET as the HTTP verb even 
though we're performing an update.  This is counter-intuitive and is painful (even dangerous) to use as 
a client.
Here's another example following the same operation of updating a customer:
GET http://api.example.com/update_customer/12345
And its evil twin:
GET http://api.example.com/customers/12345/update
You'll see this one a lot as you visit other developer's service suites.  Note that the developer is 
attempting to create RESTful resource names and has made some progress.  But you're better than this
—able to identify the verb phrase in the URL.  Notice that we don't need to use the 'update' verb phrase 
in the URL because we can rely on the HTTP verb to inform that operation.  Just to clarify, the 
following resource URL is redundant:
PUT http://api.example.com/customers/12345/update
With both PUT and 'update' in the request, we're offering to confuse our service consumers!  Is 'update' 
the resource?  So, we've spent some time beating the horse at this point.  I'm certain you understand...
Pluralization
Let's talk about the debate between the pluralizers and the “singularizers”...  Haven't heard of that 
debate?  It does exist.  Essentially, it boils down to this question...
Should URI nodes in your hierarchy be named using singular or plural nouns?  For example, should 
your URI for retrieving a representation of a customer resource look like this:
GET http://www.example.com/customer/33245
or:
05/29/12
www.RestApiTutorial.com
Page 16 of 34
VB.NET Create PDF from Excel Library to convert xlsx, xls to PDF
C#.NET convert PDF to text, C#.NET convert PDF to images How-to, VB.NET PDF, VB.NET Word, VB.NET Create fillable and editable PDF documents from Excel in Visual
convert fillable pdf to word fillable form; add fillable fields to pdf
C# Create PDF from Excel Library to convert xlsx, xls to PDF in C#
NET PDF SDK- Create PDF from Word in Visual An excellent .NET control support convert PDF to multiple Create fillable and editable PDF documents from Excel in
create fillable form pdf online; change font in pdf fillable form
RESTful Service Best Practices
GET http://www.example.com/customers/33245
There are good arguments on both sides, but the commonly-accepted practice is to always use plurals 
in node names to keep your API URIs consistent across all HTTP methods.  The reasoning is based on 
the concept that customers are a collection within the service suite and the ID (e.g. 33245) refers to one 
of those customers in the collection.
Using this rule, an example multi-node URI using pluralization would look like (emphasis added):
GET http://www.example.com/customers/33245/orders/8769/lineitems/1
with 'customers', 'orders', and 'lineitems' URI nodes all being their plural forms.
This implies that you only really need two base URLs for each root resource.  One for creation of the 
resource within a collection and the second for reading, updating and deleting the resource by its 
identifier.  For example the creation case, using customers as the example, is handled by the following 
URL:
POST http://www.example.com/customers
And the read, update and delete cases are handled by the following:
GET|PUT|DELETE http://www.example.com/customers/{id}
As mentioned earlier, there may be multiple URIs for a given resource, but as a minimum full CRUD 
capabilities are aptly handled with two simple URIs.
You ask if there is a case where pluralization doesn't make sense.  Well, yes, in fact there is.  When 
there isn't a collection concept in play.  In other words, it's acceptable to use a singularized resource 
name when there can only be one of the resource—it's a singleton resource.  For example, if there was 
a single, overarching configuration resource, you might use a singularized noun to represent that:
GET|PUT|DELETE http://www.example.com/configuration
Note the lack of a configuration ID and usage of POST verb.  And say that there was only one 
configuration per customer, then the URL might be:
GET|PUT|DELETE http://www.example.com/customers/12345/configuration
Again, no ID for the configuration and no POST verb usage. Although, I'm sure that in both of these 
cases POST usage might be argued to be valid.  Well... OK.
Returning Representations
As mentioned earlier, it is desirable for a service to support multiple representations of resources, 
including JSON and XML, as well as wrapped JSON and XML. As the default representation, the 
recommendation is JSON, but services should allow clients to specify alternative representations.
For a client to request a representation format, there is a question around whether to use the Accept 
header a file-extension-style format specifier, query-string parameter, etc.  Optimally, services would 
support all of those methods.  However, industry is currently converging on using a format specifier, 
which looks more like a file extension.  Therefore, the recommendation is that, at a minimum, services 
support the use of file extensions such as '.json', '.xml' and wrapped options, '.wjson' and '.wxml'.
05/29/12
www.RestApiTutorial.com
Page 17 of 34
RESTful Service Best Practices
Using this technique, the representation format is specified in the URI, enhancing visibility.  For 
example, GET http://www.example.com/customers.xml would return the list of customer representations 
in XML format.  Likewise, GET http://www.example.com/customers.json would return a JSON 
representation.  This makes the services simple to use from even the most basic client (such as 'curl') 
and is recommended.
Also, services should return the default representation format (presumably JSON) when a format 
specifier is not included on the url.  For example:
GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345.json
Both of the above return the 12345 customer resource in a JSON representation, which is the default 
format for this service.
GET http://www.example.com/customers/12345.xml
Returns the 12345 customer resource in an XML representation, if supported. If an XML representation 
of this resource is not supported by this service, an HTTP 404 error should be returned.
Use of the HTTP Accept header is considered by many to be a more elegant approach, and is in 
keeping with the meaning and intent of the HTTP specification with regards to how clients notify 
HTTP servers of which content types they support.  However, to support both wrapped and unwrapped 
responses from your services, in order to utilize the Accept header, you must implement your own 
custom types—since there are no standard types for these formats.  This increases the complexity of 
both clients and services greatly.  See Section 14.1 of RFC 2616 
(http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
) for details on the Accept header.  
Supporting file-extension-style format specifiers is simple, straight-forward, gets the job done in the 
fewest number of characters, and easily supports scripting—without having to leverage HTTP headers.
In general, when we talk about REST services, XML is largely irrelevant.  Barely anyone uses XML 
with REST although supporting XML is recommended.  XML standards and conventions are really not 
in play.  In particular, namespaces are not, nor should they be use in a RESTful service context.  It just 
muddies the waters and makes things more complicated.  So the XML that is returned is more JSON 
like—simple and easy to read, without the schema and namespace constraints—non-standard in other 
words, but parse-able.
Resource Discoverability Through Links (HATEOAS cont'd)
One of the guiding principals of REST (via the Uniform Interface constraint) is that application state is 
communicated via hypertext.  This is often referred to as Hypertext As The Engine of Application State 
(HATEOAS) as mentioned above in the What is Rest? Section.
According to Roy Fielding's blog (at http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven
), the most important part of a REST interface is its usage of hypertext.  Further, he states that an 
API should be usable and understandable given an initial URI without prior knowledge or out-of-band 
information.  That is, an API should be navigable via its links to various components of the data.  
Returning only data representations is discouraged.
This practice is not often followed by current industry leaders in services, reflecting that HATEOAS 
05/29/12
www.RestApiTutorial.com
Page 18 of 34
RESTful Service Best Practices
usage is higher on the maturity model.  Looking around at many services, convention is to return more 
data and less (or no) links.  This is contrary to Fielding's REST constraints.  Fielding says, “Every 
addressable unit of information carries an address... Query results are represented by a list of links with 
summary information, not by arrays of object representations.”
On the other hand, simply returning collections of links can be a major cause of network chattiness.  In 
the real world, depending on requirements or use cases, chattiness of the API interface is managed by 
balancing how much “summary” data is included along with the relational hypertext links in service 
responses.
Also, full use of HATEOAS can increase implementation complexity and impose a significant burden 
on service clients, decreasing developer productivity on both client and server ends of the equation.  
Consequently, it is imperative to balance hyperlinking service implementations with available 
development resources.
A minimal set of hyperlinking practices provides major gains in service usability, navigability and 
understandability while minimizing development impact and reducing the coupling between client and 
server.  These minimal recommendations are resources created via POST and for collections returned 
from GET requests, with additional recommendations for pagination cases, which are described below.
Minimal Linking Recommendations
In create use cases, the URI (link) for the newly-created resource should be returned in the Location 
response header and the response body be empty—or contain only the ID of the newly-created 
resource.
For collections of representations being returned from a service, each representation should minimally 
carry a 'self' link property in its own links collection.  Other links may be present in the returned as a 
separate links collection to facilitate pagination, with 'first', 'previous', 'next', 'last' links where 
applicable.
See the examples in the Link Format section below for more information.
Link Format
Regarding overall link format standards it is recommended to adhere to some semblance of the Atom, 
AtomPub, or Xlink style.  JSON-LD is getting some traction too, but is not widely adopted yet (if it 
ever will be).  Most widespread in the industry is usage of the Atom link style with a “rel” element and 
an “href” element that contains the full URI for the resource without any authentication or query-string 
parameters.  The “rel” element, can contain the standard values "alternate", "related", "self", 
"enclosure", and "via", plus “first”, “last”, “previous”, “next” for pagination links.  Use them where 
they make sense and add your own when needed.
Some of the XML Atom format concepts are somewhat irrelevant for links being represented in JSON.  
For instance, the METHOD property is not needed for a RESTful resource since the URIs are the same 
for a given resource, with all of the HTTP methods being supported (for CRUD behavior)--so listing 
them individually is overkill.
Let's make all this talk a little more concrete with some examples.  Here's what the response would 
05/29/12
www.RestApiTutorial.com
Page 19 of 34
RESTful Service Best Practices
look like after creating a new resource with a call to:
POST http://api.example.com/users
And here's an example set of response headers with the Location header set containing the new 
resource URI:
HTTP/1.1 200 OK
Status: 200
Connection: close
Content-Type: application/json; charset=utf-8
Location: http://api.example.com/users/12346
The body is either empty, or contains a wrapped response (see Wrapped Responses below).
Here is an example JSON response to a GET request that returns a collection of representations without 
pagination involved:
{“data”:[{“user_id”:”42”, “name”:”Bob”, “links”:[{“rel”:”self”, 
“href”:”http://api.example.com/users/42”}]}, {“user_id”:”22”, “name”:”Frank”, “links”:
[{“rel”:”self”, “href”:”http://api.example.com/users/22”}]}, {“user_id”:”125”, “name”: “Sally”, 
“links”:[{“rel”:”self”, “href”:”http://api.example.com/users/125”}]}]}
Note the links array containing a single reference to “self” for each item in the collection.  This array 
could potentially contain other relationships, such as children, parent, etc.
The final example is a JSON response to a GET request that returns a collection where pagination is 
involved (we're using three items per page) and we're on the third page of the collection:
{“data”:[{“user_id”:”42”, “name”:”Bob”, “links”:[{“rel”:”self”, 
“href”:”http://api.example.com/users/42”}]}, {“user_id”:”22”, “name”:”Frank”, “links”:
[{“rel”:”self”, “href”:”http://api.example.com/users/22”}]}, {“user_id”:”125”, “name”: “Sally”, 
“links”:[{“rel”:”self”, “href”:”http://api.example.com/users/125”}]}], “links”:[{“rel”:“first”, 
“href”:”http://api.example.com/users?offset=0&limit=3”}, {“rel”:“last”, 
“href”:”http://api.example.com/users?offset=55&limit=3”}, {“rel”:“previous”, 
“href”:”http://api.example.com/users?offset=3&limit=3”}, {“rel”:”next”, 
“href”:”http://api.example.com/users?offset=9&limit=3”}]}
In this example, the links collection in the response is populated for pagination purposes along with the 
link to “self” in each of the items in the collection.  There could be additional links here related to the 
collection but not related to pagination.  The simple summary is, there are two places to include links in 
a collection.  For each item in the collection (those in the data object, which is the collection of 
representations requested), include a links collection that, minimally, would contain a “self” reference.  
Then, in a separate object, links, include links that apply to the entire collection as applicable, such as 
pagination-related links.
For the create use case—create via POST, include a Location header with a link to the newly-created 
object.
05/29/12
www.RestApiTutorial.com
Page 20 of 34
Documents you may be interested
Documents you may be interested