asp.net c# pdf to image : Convert an existing form into a fillable pdf form control Library platform web page .net html web browser RESTful_Best_Practices-v1_10-part1827

RESTful Service Best Practices
RESTful Service Best Practices
Recommendations for Creating Web Services
Todd Fredrich
Pearson eCollege
toddf@ecollege.com
www.RestApiTutorial.com
05/29/12
www.RestApiTutorial.com
Page 1 of 34
Convert an existing form into a 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 to fillable pdf form; c# fill out pdf form
Convert an existing form into a 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
allow users to attach to pdf form; change font size in fillable pdf form
RESTful Service Best Practices
05/29/12
www.RestApiTutorial.com
Page 2 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. NET PDF package, you can add form fields to existing pdf files, delete or
convert html form to pdf fillable form; create a pdf form to fill out and save
C# Create PDF Library SDK to convert PDF from other file formats
Create fillable PDF document with fields. Create(2); // Save the new created PDF document into file doc.Save Load PDF Document from existing PDF file Using C#.
convert word to pdf fillable form online; change font size in pdf fillable form
RESTful Service Best Practices
Table of Contents
Document History......................................................................................................................................5
Who Should Read This Document.............................................................................................................5
Introduction................................................................................................................................................6
What is REST?...........................................................................................................................................6
Uniform Interface..................................................................................................................................7
Resource-Based................................................................................................................................7
Manipulation of Resources Through Representations......................................................................7
Self-descriptive Messages................................................................................................................7
Hypermedia as the Engine of Application State (HATEOAS).........................................................7
Stateless.................................................................................................................................................7
Cacheable..............................................................................................................................................8
Client–server.........................................................................................................................................8
Layered system......................................................................................................................................8
Code on demand (optional)...................................................................................................................8
REST Quick Tips.......................................................................................................................................9
Use HTTP Verbs to Mean Something...................................................................................................9
Sensible Resource Names.....................................................................................................................9
XML and JSON.....................................................................................................................................9
Create Fine-Grained Resources...........................................................................................................10
Consider Connectedness......................................................................................................................10
Definitions................................................................................................................................................10
Idempotence........................................................................................................................................10
Safety...................................................................................................................................................11
HTTP Verbs..............................................................................................................................................11
GET.....................................................................................................................................................11
PUT.....................................................................................................................................................12
POST...................................................................................................................................................12
PUT vs POST for Creation..................................................................................................................13
DELETE..............................................................................................................................................13
Resource Naming.....................................................................................................................................14
Resource URI Examples.....................................................................................................................15
Resource Naming Anti-Patterns..........................................................................................................16
Pluralization.........................................................................................................................................16
Returning Representations.......................................................................................................................17
Resource Discoverability Through Links (HATEOAS cont'd)...........................................................18
Minimal Linking Recommendations..............................................................................................19
Link Format....................................................................................................................................19
Wrapped Responses.............................................................................................................................21
Handling Cross-Domain Issues...........................................................................................................22
Supporting CORS...........................................................................................................................22
Supporting JSONP..........................................................................................................................22
Querying, Filtering and Pagination..........................................................................................................23
05/29/12
www.RestApiTutorial.com
Page 3 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 Load PDF from existing documents and image in SQL as it can be easily integrated into many MS
create fillable pdf form from word; convert pdf forms to fillable
C# Create PDF from OpenOffice to convert odt, odp files to PDF in
An advanced .NET control to change ODT, ODS, ODP forms to fillable PDF formats in Visual C# .NET. Description: Convert to PDF/TIFF and save it into stream.
pdf form filler; convert word to pdf fillable form
RESTful Service Best Practices
Limiting Results..................................................................................................................................24
Limiting via the Range Header.......................................................................................................25
Limiting via Query-String Parameters............................................................................................25
Range-Based Responses.................................................................................................................25
Pagination............................................................................................................................................26
Filtering and Sorting Results...............................................................................................................27
Filtering..........................................................................................................................................27
Sorting............................................................................................................................................28
Service Versioning...................................................................................................................................28
Date/Time Handling.................................................................................................................................29
Date/Time Serialization In Body Content...........................................................................................29
Date/Time Serialization In HTTP Headers..........................................................................................29
Securing Services.....................................................................................................................................30
Authentication.....................................................................................................................................30
Transport Security...............................................................................................................................30
Authorization.......................................................................................................................................31
Application Security............................................................................................................................31
Caching and Scalability...........................................................................................................................31
The ETag Header............................................................................................................................32
HTTP Status Codes (Top 10)...................................................................................................................33
Additional Resources...............................................................................................................................34
Books...................................................................................................................................................34
Websites...............................................................................................................................................34
05/29/12
www.RestApiTutorial.com
Page 4 of 34
VB.NET Create PDF from OpenOffice to convert odt, odp files to PDF
Page: Insert PDF Pages. Page: Delete Existing PDF Pages. Edit Bookmark. Metadata: Edit, Delete Metadata. Form Process. Convert OpenOffice Spreadsheet data to PDF.
create fillable forms in pdf; convert word doc to fillable pdf form
C# Create PDF from Excel Library to convert xlsx, xls to PDF in C#
An excellent .NET control support convert PDF to multiple Turn all Excel spreadsheet into high quality PDF Create fillable and editable PDF documents from
pdf create fillable form; convert pdf to form fill
RESTful Service Best Practices
Document History
Date
Version
Description
Feb 10, 2012
Draft
Initial draft version.
Apr 24, 2012
v1.0
Initial public (non-draft) version.
May 29, 2012
v1.1
Minor updates to correct misspellings and clarify wording after 
feedback from API Best Practices Task force.
Who Should Read This Document
This best-practices document is intended for developers who are interested in creating RESTful Web 
services that provide high reliability and consistency across multiple service suites.  By following these 
guidelines, services are well positioned for rapid, widespread, public adoption by both internal and 
external clients.
The guidelines in this document are also appropriate for support engineers where they desire to services 
developed using these best practices.  While their concerns may be focused on caching practices, proxy 
rules, monitoring, security and such, this document may be useful as an overarching service 
documentation guide of sorts.
Additionally, management personnel may benefit from these guidelines by endeavoring to understand 
the effort required to create services that are publicly consumable and offer high levels of consistency 
across their service suites.
05/29/12
www.RestApiTutorial.com
Page 5 of 34
C# Create PDF from Word Library to convert docx, doc to PDF in C#.
to turn all Word text and image content into high quality PDF without losing formatting. Convert multiple pages Word to fillable and editable PDF documents in
auto fill pdf form from excel; convert pdf to fillable pdf form
C# Create PDF from PowerPoint Library to convert pptx, ppt to PDF
Excellent .NET control for turning all PowerPoint presentation into high quality PDF Convert multiple pages PowerPoint to fillable and editable PDF
form pdf fillable; adding signature to pdf form
RESTful Service Best Practices
Introduction
There are numerous resources on best practices for creating RESTful web services (see the Resources 
section at the end of this document).  Many of the available resources are conflicting, depending on 
when they were written.  Plus, reading and comprehending several books on the subject in order to 
implement services “tomorrow” is not doable.  In order to facilitate the quick uptake and understanding 
of RESTful concepts, without requiring the reading of at least three to five books on the subject, this 
guide is meant to speed up the process—condensing REST best practices and conventions into just the 
high points with not a lot of discussion.
REST is more a collection of principles than it is a set of standards.  Other than its over-arching six 
constraints nothing is dictated.  There are "best practices" and de-facto standards but those are 
constantly evolving—with religious battles waging continuously.
Designed to be brief, this document provides recommendations and some cookbook-style discussion on 
many of the common questions around REST and provides some short background information to offer 
support for effective creation of real-world, production-ready, consistent RESTful services.  This 
document aggregates information available in other sources, adapting it with experience gained through 
hard knocks.
There is still considerable debate as to whether REST is better than SOAP (and vice versa), and perhaps 
there are still reasons to create SOAP services.  While touching on SOAP, this document won't spend a 
lot of time discussing the relative merits.  Instead, because technology and the industry marches on, we 
will proceed with the assumption that leveraging REST is the current best practice for Web service 
creation.
The first section offers an overview of what REST is, its constraints, and what makes it unique.  The 
second section supplies some quick tips as little reminders of REST service concepts.  Later sections go 
more in depth to provide the Web service creator more support and discussion around the nitty-gritty 
details of creating high-quality REST services capable of being publicly exposed in a production 
environment.
What is REST?
The REST architectural style describes six constraints.  These constraints, applied to the architecture, 
were originally communicated by Roy Fielding in his doctoral dissertation (see 
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
) and defines the basis of 
RESTful-style.
The six constraints are:
• Uniform Interface
• Stateless
• Cacheable
• Client-Server
• Layered System
• Code on Demand
05/29/12
www.RestApiTutorial.com
Page 6 of 34
VB.NET Create PDF from PowerPoint Library to convert pptx, ppt to
Page: Insert PDF Pages. Page: Delete Existing PDF Pages. Bookmark. Metadata: Edit, Delete Metadata. Form Process. Convert multiple pages PowerPoint to fillable and
convert pdf fillable form; pdf form fill
VB.NET Create PDF from Word Library to convert docx, doc to PDF in
Page: Insert PDF Pages. Page: Delete Existing PDF Pages. Edit Bookmark. Metadata: Edit, Delete Metadata. Form Process. Convert multiple pages Word to fillable and
create pdf fillable form; convert pdf to fillable form
RESTful Service Best Practices
A more detailed discussion of the constraints follows:
Uniform Interface
The uniform interface constraint defines the interface between clients and servers.  It simplifies and 
decouples the architecture, which enables each part to evolve independently. The four guiding 
principles of the uniform interface are:
Resource-Based
Individual resources are identified in requests using URIs as resource identifiers. The resources 
themselves are conceptually separate from the representations that are returned to the client. For 
example, the server does not send its database, but rather, some HTML, XML or JSON that represents 
some database records expressed, for instance, in Finnish and encoded in UTF-8, depending on the 
details of the request and the server implementation.
Manipulation of Resources Through Representations
When a client holds a representation of a resource, including any metadata attached, it has enough 
information to modify or delete the resource on the server, provided it has permission to do so.
Self-descriptive Messages
Each message includes enough information to describe how to process the message. For example, 
which parser to invoke may be specified by an Internet media type (previously known as a MIME 
type). Responses also explicitly indicate their cache-ability.
Hypermedia as the Engine of Application State (HATEOAS)
Clients deliver state via body contents, query-string parameters, request headers and the requested URI 
(the resource name).  Services deliver state to clients via body content, response codes, and response 
headers.  This is technically referred-to as hypermedia (or hyperlinks within hypertext).
Aside from the description above, HATEOS also means that, where necessary, links are contained in 
the returned body (or headers) to supply the URI for retrieval of the object itself or related objects.  
We'll talk about this in more detail later.
The uniform interface that any REST services must provide is fundamental to its design.
Stateless
As REST is an acronym for REpresentational State Transfer, statelessness is key.  Essentially, what 
this means is that the necessary state to handle the request is contained within the request itself, 
whether as part of the URI, query-string parameters, body, or headers.  The URI uniquely identifies the 
resource and the body contains the state (or state change) of that resource.  Then after the server does 
it's processing, the appropriate state, or the piece(s) of state that matter, are communicated back to the 
client via headers, status and response body.
05/29/12
www.RestApiTutorial.com
Page 7 of 34
RESTful Service Best Practices
Most of us who have been in the industry for a while are accustomed to programming within a 
container which provides us with the concept of “session” which maintains state across multiple HTTP 
requests.  In REST, the client must include all information for the server to fulfill the request, resending 
state as necessary if that state must span multiple requests.  Statelessness enables greater scalability 
since the server does not have to maintain, update or communicate that session state.  Additionally, load 
balancers don't have to worry about session affinity for stateless systems.
So what's the difference between state and a resource?  State, or application state, is that which the 
server cares about to fulfill a request—data necessary for the current session or request.  A resource, or 
resource state, is the data that defines the resource representation—the data stored in the database, for 
instance.  Consider application state to be data that could vary by client, and per request.  Resource 
state, on the other hand, is constant across every client who requests it.
Ever had back-button issues with a web application where it went AWOL at a certain point because it 
expected you to do things in a certain order?  That's because it violated the statelessness principle. 
There are cases that don't honor the statelessness principle, such as three-legged OAuth, API call rate 
limiting, etc.  However, make every effort to ensure that application state doesn't span multiple requests 
of your service(s).
Cacheable
As on the World Wide Web, clients can cache responses. Responses must therefore, implicitly or 
explicitly, define themselves as cacheable, or not, to prevent clients reusing stale or inappropriate data 
in response to further requests. Well-managed caching partially or completely eliminates some client–
server interactions, further improving scalability and performance.
Client–server
The uniform interface separates clients from servers. This separation of concerns means that, for 
example, clients are not concerned with data storage, which remains internal to each server, so that the 
portability of client code is improved. Servers are not concerned with the user interface or user state, so 
that servers can be simpler and more scalable. Servers and clients may also be replaced and developed 
independently, as long as the interface is not altered.
Layered system
A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary 
along the way. Intermediary servers may improve system scalability by enabling load-balancing and by 
providing shared caches. Layers may also enforce security policies.
Code on demand (optional)
Servers are able to temporarily extend or customize the functionality of a client by transferring logic to 
it that it can execute. Examples of this may include compiled components such as Java applets and 
client-side scripts such as JavaScript.
Complying with these constraints, and thus conforming to the REST architectural style, will enable any 
05/29/12
www.RestApiTutorial.com
Page 8 of 34
RESTful Service Best Practices
kind of distributed hypermedia system to have desirable emergent properties, such as performance, 
scalability, simplicity, modifiability, visibility, portability and reliability.
NOTE: The only optional constraint of REST architecture is code on demand. If a service violates any 
other constraint, it cannot strictly be referred to as RESTful.
REST Quick Tips
Whether it's technically RESTful or not (according to the six constraints mentioned above), here are a 
few recommended REST-like concepts that will result in better, more usable services:
Use HTTP Verbs to Mean Something
Any API consumer is capable of sending GET, POST, PUT, and DELETE verbs, and they greatly 
enhance the clarity of what a given request does. Also, GET requests must not change any underlying 
resource data.  Measurements and tracking may still occur, which updates data, but not resource data 
identified by the URI.
Sensible Resource Names
Having sensible resource names or paths (e.g., /posts/23 instead of /api?type=posts&id=23) improves 
the clarity of what a given request does. Using URL query-string parameters is fantastic for filtering, 
but not for resource names.
Appropriate resource names provide context for a service request, increasing understandability of the 
service API.  Resources are viewed hierarchically via their URI names, offering consumers a friendly, 
easily-understood hierarchy of resources to leverage in their applications.
Resource names should be nouns—avoid verbs as resource names.  It makes things more clear.  Use the 
HTTP methods to specify the verb portion of the request.
XML and JSON
Favor JSON support as the default, but unless the costs of offering both JSON and XML are staggering, 
offer them both.  Ideally, let consumers switch between them by just changing an extension from .xml 
to .json.  In addition, for supporting AJAX-style user interfaces, a wrapped response is very helpful.  
Provide a wrapped response, either by default or for separate extensions, such as .wjson and .wxml to 
indicate the client is requesting a wrapped JSON or XML response (see Wrapped Responses below).
JSON in regards to a "standard" has very few requirements.  And those requirements are only 
syntactical in nature, not about content format or layout.  In other words, the JSON response to a REST 
service call is very much part of the contract—not described in a standard.  More about the JSON data 
format can be found at http://www.json.org/
.
Regarding XML use in REST services, XML standards and conventions are really not in play other 
than to utilize syntactically correct tags and text.  In particular, namespaces are not, nor should they be 
use in a RESTful service context.  XML that is returned is more JSON like—simple and easy to read, 
without the schema and namespace details present—just data and links.  If it ends up being more 
05/29/12
www.RestApiTutorial.com
Page 9 of 34
RESTful Service Best Practices
complex than this, see the first paragraph of this tip—the cost of XML will be staggering.  In our 
experience few consumers uses the XML responses anyway.  This is the last 'nod' before it gets phased 
out entirely.
Create Fine-Grained Resources
When starting out, it's much easier to create APIs that mimic the underlying application domain or 
database architecture of your system.  Eventually, you'll want aggregate services—services that utilize 
multiple underlying resources to reduce chattiness.  But it's much easier to create larger resources later 
from individual resources than it is to create fine-grained or individual resources from larger 
aggregates.  Make it easy on yourself and start with small, easily defined resources, providing CRUD 
functionality on those.  You can create those use-case-oriented, chattiness-reducing resources later.
Consider Connectedness
One of the principles of REST is connectedness—via hypermedia links.  While services are still useful 
without them, APIs become more self-descriptive when links are returned in the response.  At the very 
least, a 'self' reference informs clients how the data was or can be retrieved.  Additionally, utilize the 
Location header to contain a link on resource creation via POST.  For collections returned in a response 
that support pagination, 'first', 'last', 'next' and 'prev' links at a minimum are very helpful.
Definitions
Idempotence
Contrary to how it sounds, make no mistake, this has no relation to certain areas of disfunction.  From 
Wikipedia:
In computer science, the term idempotent is used more comprehensively to describe an 
operation that will produce the same results if executed once or multiple times.  This may 
have a different meaning depending on the context in which it is applied. In the case of 
methods or subroutine calls with side effects, for instance, it means that the modified state 
remains the same after the first call.
From a RESTful service standpoint, for an operation (or service call) to be idempotent, clients can 
make that same call repeatedly while producing the same result—operating much like a “setter” 
method in a programming language.  In other words, making multiple identical requests has the same 
effect as making a single request. Note that while idempotent operations produce the same result on the 
server (side effects), the response itself may not be the same (e.g. a resource's state may change 
between requests).
The PUT and DELETE methods are defined to be idempotent.  However, read the caveat on DELETE 
in the HTTP Verbs, DELETE section below.
GET, HEAD, OPTIONS and TRACE methods are defined as idempotent also, since they are defined as 
safe.  Read the section on safety below.
05/29/12
www.RestApiTutorial.com
Page 10 of 34
Documents you may be interested
Documents you may be interested