c# webbrowser pdf : Creating bookmarks in pdf files software Library dll windows asp.net winforms web forms api-design-ebook-2012-030-part543

Web API Design 
Crafting Interfaces that Developers Love 
Brian Mulloy 
Creating bookmarks in pdf files - add, remove, update PDF bookmarks in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your C# Project with Rapid PDF Internal Navigation Via Bookmark and Outline
copy pdf bookmarks; how to create bookmark in pdf with
Creating bookmarks in pdf files - VB.NET PDF bookmark library: add, remove, update PDF bookmarks in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your VB.NET Project with Rapid PDF Internal Navigation Via Bookmark and Outline
how to add a bookmark in pdf; how to bookmark a page in pdf document
     
 
Table of Contents 
Web API Design  - Crafting Interfaces that Developers Love 
Introduction ............................................................................................................................................ 3 
Nouns are good; verbs are bad ......................................................................................................... 4 
Plural nouns and concrete names ................................................................................................... 8 
Simplify associations - sweep complexity under the ‘?’ ........................................................... 9 
Handling errors ................................................................................................................................... 10 
Tips for versioning.............................................................................................................................. 13 
Pagination and partial response.................................................................................................... 16 
What about responses that don’t involve resources? ............................................................ 19 
Supporting multiple formats .......................................................................................................... 20 
What about attribute names? ......................................................................................................... 21 
Tips for search ...................................................................................................................................... 22 
Consolidate API requests in one subdomain ............................................................................. 23 
Tips for handling exceptional behavior ...................................................................................... 25 
Authentication...................................................................................................................................... 27 
Making requests on your API .......................................................................................................... 28 
Chatty APIs ............................................................................................................................................. 30 
Complement with an SDK ................................................................................................................. 31 
The API Façade Pattern ..................................................................................................................... 32 
C# Create PDF Library SDK to convert PDF from other file formats
Gratis control for creating PDF from multiple image formats such as tiff, jpg, png Create and save editable PDF with a blank page, bookmarks, links, signatures
bookmark template pdf; adding bookmarks to pdf document
VB.NET Create PDF Library SDK to convert PDF from other file
Gratis control for creating PDF from multiple image formats such as tiff, jpg, png Create and save editable PDF with a blank page, bookmarks, links, signatures
pdf export bookmarks; how to bookmark a pdf in reader
Web API Design - Crafting Interfaces that Developers Love 
         
 
Introduction 
If you’re reading this, chances are that you care about designing Web APIs that developers 
will love and that you’re interested in applying proven design principles and best practices 
to your Web API.  
One of the sources for our design thinking is REST. Because REST is an architectural style 
and not a strict standard, it allows for a lot of flexibly. Because of that flexibility and 
freedom of structure, there is also a big appetite for design best practices. 
This e-book is a collection of design practices that we have developed in collaboration with 
some of the leading API teams around the world, as they craft their API strategy through a 
design workshop that we provide at Apigee.  
We call our point of view in API design “pragmatic REST”, because it places the success of 
the developer over and above any other design principle. The developer is the customer for 
the Web API. The success of an API design is measured by how quickly developers can get 
up to speed and start enjoying success using your API.  
We’d love your feedback – whether you agree, disagree, or have some additional practices 
and tips to add. The API Craft Google Group is a place where Web API design enthusiasts 
come together to share and debate design practices – we’d love to see you there. 
Are you a Pragmatist or a RESTafarian? 
Let’s start with our overall point of view on API design. We advocate pragmatic, not 
dogmatic REST. What do we mean by dogmatic?    
You might have seen discussion threads on true REST - some of them can get pretty strict 
and wonky.  Mike Schinkel sums it up well - defining a RESTafarian as follows: 
“A RESTifarian is a zealous proponent of the REST software architectural style as defined by 
Roy T. Fielding in Chapter 5 of his PhD. dissertation at UC Irvine. You can find RESTifarians in 
the wild on the REST-discuss mailing list. But be careful, RESTifarians can be extremely 
meticulous when discussing the finer points of REST …” 
Our view: approach API design from the ‘outside-in’ perspective. This means we start by 
asking - what are we trying to achieve with an API? 
The API’s job is to make the developer as successful as possible. The orientation for APIs is 
to think about design choices from the application developer’s point of view.  
XDoc.Word for .NET, Advanced .NET Word Processing Features
Viewing, editing, converting, processing, creating, annotating and zooming & rotation; Outlines, bookmarks, & thumbnail Convert Word to PDF; Convert Word to
add bookmarks to pdf online; copy bookmarks from one pdf to another
VB.NET PDF: Basic SDK Concept of XDoc.PDF
features can be integrated into your VB.NET project, such as annotation creating, deleting, modifying This class describes bookmarks in a PDF document.
creating bookmarks in pdf files; adding bookmarks to a pdf
Web API Design - Crafting Interfaces that Developers Love 
         
 
Why? Look at the value chain below – the application developer is the lynchpin of the 
entire API strategy. The primary design principle when crafting your API should be to 
maximize developer productivity and success.  This is what we call pragmatic REST. 
Pragmatic REST is a design problem 
You have to get the design right, because design communicates how something will be 
used. The question becomes - what is the design with optimal benefit for the app 
developer? 
The developer point of view is the guiding principle for all the specific tips and best 
practices we’ve compiled. 
Nouns are good; verbs are bad 
The number one principle in pragmatic RESTful design is: keep simple things simple. 
Keep your base URL simple and intuitive 
The base URL is the most important design affordance of your API.  A simple and intuitive 
base URL design makes using your API easy. 
Affordance is a design property that communicates how something should be used without 
requiring documentation.  A door handle's design should communicate whether you pull or 
push. Here's an example of a conflict between design affordance and documentation - not 
an intuitive interface! 
How to C#: Basic SDK Concept of XDoc.PDF for .NET
annotation features can be integrated into your C# project, such as annotation creating, deleting, modifying This class describes bookmarks in a PDF document
adding bookmarks to pdf; create bookmark pdf
How to C#: Basic SDK Concept of XDoc.PowerPoint
Conversely, conversion from PDF to PowerPoint (.PPTX C# project, such as annotation creating, deleting, modifying This class describes bookmarks in a PowerPoint
bookmark pdf acrobat; bookmark pdf reader
Web API Design - Crafting Interfaces that Developers Love 
         
 
A key litmus test we use for Web API design is that there should be only 2 base URLs per 
resource. Let's model an API around a simple object or resource, a dog, and create a Web 
API for it. 
The first URL is for a collection; the second is for a specific element in the collection.  
/dogs  
/dogs/1234 
Boiling it down to this level will also force the verbs out of your base URLs.    
Keep verbs out of your base URLs 
Many Web APIs start by using a method-driven approach to URL design. These method-
based URLs sometimes contain verbs - sometimes at the beginning, sometimes at the end. 
For any resource that you model, like our dog, you can never consider one object in 
isolation. Rather, there are always related and interacting resources to account for - like 
owners, veterinarians, leashes, food, squirrels, and so on. 
How to C#: Basic SDK Concept of XDoc.Word
Conversely, conversion from PDF to Word (.docx) is C# project, such as annotation creating, deleting, modifying This class describes bookmarks in a Word document
how to bookmark a pdf file in acrobat; how to add bookmarks on pdf
How to C#: Basic SDK Concept of XDoc.Excel
Conversely, conversion from PDF to Excel (.XLSX) is also C# project, such as annotation creating, deleting, modifying This class describes bookmarks in a Excel
create bookmarks in pdf from excel; auto bookmark pdf
Web API Design - Crafting Interfaces that Developers Love 
         
 
Think about the method calls required to address all the objects in the dogs’ world. The 
URLs for our resource might end up looking something like this. 
It's a slippery slope - soon you have a long list of URLs and no consistent pattern making it 
difficult for developers to learn how to use your API. 
Use HTTP verbs to operate on the collections and elements. 
For our dog resources, we have two base URLs that use nouns as labels, and we can operate 
on them with HTTP verbs. Our HTTP verbs are POST, GET, PUT, and DELETE. (We think of 
them as mapping to the acronym, CRUD (Create-Read-Update-Delete).)   
With our two resources (
/dogs
and 
/dogs/1234
) and the four HTTP verbs, we have a 
rich set of capability that's intuitive to the developer. Here is a chart that shows what we 
mean for our dogs. 
Web API Design - Crafting Interfaces that Developers Love 
         
 
Resource 
POST 
create 
GET 
read 
PUT 
update 
DELETE 
delete 
/dogs 
Create a new 
dog 
List dogs 
Bulk update 
dogs 
Delete all dogs 
/dogs/1234 
Error 
Show Bo 
If exists update 
Bo 
If not error 
Delete Bo 
The point is that developers probably don't need the chart to understand how the API 
behaves. They can experiment with and learn the API without the documentation.   
In summary:  
Use two base URLs per resource.   
Keep verbs out of your base URLs.  
Use HTTP verbs to operate on the collections and elements. 
Web API Design - Crafting Interfaces that Developers Love 
         
 
Plural nouns and concrete names  
Let’s explore how to pick the nouns for your URLs. 
Should you choose singular or plural nouns for your resource names? You'll see popular 
APIs use both. Let's look at a few examples: 
Foursquare  
GroupOn 
Zappos 
/checkins 
/deals  
/Product 
Given that the first thing most people probably do with a RESTful API is a GET, we think it 
reads more easily and is more intuitive to use plural nouns. But above all, avoid a mixed 
model in which you use singular for some resources, plural for others. Being consistent 
allows developers to predict and guess the method calls as they learn to work with your 
API. 
Concrete names are better than abstract 
Achieving pure abstraction is sometimes a goal of API architects. However, that abstraction 
is not always meaningful for developers. 
Take for example an API that accesses content in various forms  - blogs, videos, news 
articles, and so on. 
An API that models everything at the highest level of abstraction - as 
/items
or 
/assets
in our example - loses the opportunity to paint a tangible picture for developers to know 
what they can do with this API. It is more compelling and useful to see the resources listed 
as blogs, videos, and news articles. 
The level of abstraction depends on your scenario. You also want to expose a manageable 
number of resources. Aim for concrete naming and to keep the number of resources 
between 12 and 24. 
In summary, an intuitive API uses plural rather than singular nouns, and concrete rather 
than abstract names. 
Web API Design - Crafting Interfaces that Developers Love 
         
 
Simplify associations - sweep complexity under the ‘?’ 
In this section, we explore API design considerations when handling associations between 
resources and parameters like states and attributes. 
Associations 
Resources almost always have relationships to other resources. What's a simple way to 
express these relationships in a Web API? 
Let's look again at the API we modeled in nouns are good, verbs are bad - the API that 
interacts with our dogs resource. Remember, we had two base URLs: /dogs and 
dogs/1234. 
We're using HTTP verbs to operate on the resources and collections. Our dogs belong to 
owners. To get all the dogs belonging to a specific owner, or to create a new dog for that 
owner, do a 
GET
or a POST: 
GET /owners/5678/dogs 
POST /owners/5678/dogs 
Now, the relationships can be complex. Owners have relationships with veterinarians, who 
have relationships with dogs, who have relationships with food, and so on. It's not 
uncommon to see people string these together making a URL 5 or 6 levels deep. Remember 
that once you have the primary key for one level, you usually don't need to include the 
levels above because you've already got your specific object. In other words, you shouldn't 
need too many cases where a URL is deeper than what we have above 
/resource/identifier/resource.
Sweep complexity behind the ‘?’
Most APIs have intricacies beyond the base level of a resource. Complexities can include 
many states that can be updated, changed, queried, as well as the attributes associated with 
a resource. 
Make it simple for developers to use the base URL by putting optional states and attributes 
behind the HTTP question mark. To get all red dogs running in the park: 
GET /dogs?color=red&state=running&location=park 
In summary, keep your API intuitive by simplifying the associations between resources, 
and sweeping parameters and other complexities under the rug of the HTTP question 
mark. 
Web API Design - Crafting Interfaces that Developers Love 
10          
 
Handling errors 
Many software developers, including myself, don't always like to think about exceptions 
and error handling but it is a very important piece of the puzzle for any software developer, 
and especially for API designers. 
Why is good error design especially important for API designers? 
From the perspective of the developer consuming your Web API, everything at the other 
side of that interface is a black box. Errors therefore become a key tool providing context 
and visibility into how to use an API. 
First, developers learn to write code through errors.  The "test-first" concepts of the 
extreme programming model and the more recent "test driven development" models 
represent a body of best practices that have evolved because this is such an important and 
natural way for developers to work. 
Secondly, in addition to when they're developing their applications, developers depend on 
well-designed errors at the critical times when they are troubleshooting and resolving 
issues after the applications they've built using your API are in the hands of their users. 
How to think about errors in a pragmatic way with REST? 
Let's take a look at how three top APIs approach it. 
Facebook 
HTTP Status Code: 200 
{"type" : "OauthException", "message":"(#803) Some of the 
aliases you requested do not exist: foo.bar"} 
Twilio 
HTTP Status Code: 401 
{"status" : "401", "message":"Authenticate","code": 20003, "more 
info": "http://www.twilio.com/docs/errors/20003"} 
SimpleGeo 
HTTP Status Code: 401 
{"code" : 401, "message": "Authentication Required"} 
Documents you may be interested
Documents you may be interested