c# webbrowser pdf : How to bookmark a pdf file software application dll windows html winforms web forms api-design-ebook-2012-031-part544

Web API Design - Crafting Interfaces that Developers Love 
11          
 
Facebook 
No matter what happens on a Facebook request, you get back the 200-status code - 
everything is OK. Many error messages also push down into the HTTP response. Here they 
also throw an #803 error but with no information about what #803 is or how to react to it. 
Twilio 
Twilio does a great job aligning errors with HTTP status codes. Like Facebook, they provide 
a more granular error message but with a link that takes you to the documentation. 
Community commenting and discussion on the documentation helps to build a body of 
information and adds context for developers experiencing these errors. 
SimpleGeo 
SimpleGeo provides error codes but with no additional value in the payload.  
A couple of best practices 
Use HTTP status codes 
Use HTTP status codes and try to map them cleanly to relevant standard-based codes. 
There are over 70 HTTP status codes. However, most developers don't have all 70 
memorized. So if you choose status codes that are not very common you will force 
application developers away from building their apps and over to Wikipedia to figure out 
what you're trying to tell them.  
Therefore, most API providers use a small subset. For example, the Google GData API uses 
only 10 status codes; Netflix uses 9, and Digg, only 8. 
Google GData  
200  201  304  400  401  403  404  409  410  500 
Netflix 
200  201  304  400  401  403  404  412  500 
Digg  
200  400  401  403  404  410  500  503 
How many status codes should you use for your API? 
When you boil it down, there are really only 3 outcomes in the interaction between an app 
and an API: 
Everything worked - success 
The application did something wrong – client error 
The API did something wrong – server error 
How to bookmark a pdf file - 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
creating bookmarks pdf files; edit pdf bookmarks
How to bookmark a pdf file - 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 create bookmark in pdf automatically; bookmarks in pdf files
Web API Design - Crafting Interfaces that Developers Love 
12          
 
Start by using the following 3 codes. If you need more, add them. But you shouldn't need to 
go beyond 8. 
200 - OK 
400 - Bad Request 
500 - Internal Server Error 
If you're not comfortable reducing all your error conditions to these 3, try picking among 
these additional 5: 
201 - Created 
304 - Not Modified 
404 – Not Found 
401 - Unauthorized 
403 - Forbidden 
(Check out this good Wikipedia entry for all HTTP Status codes.) 
It is important that the code that is returned can be consumed and acted upon by the 
application's business logic - for example, in an if-then-else, or a case statement.  
Make messages returned in the payload as verbose as possible. 
Code for code 
200 – OK 
401 – Unauthorized 
Message for people 
{"developerMessage" : "Verbose, plain language description of 
the problem for the app developer with hints about how to fix 
it.", "userMessage":"Pass this message on to the app user if 
needed.", "errorCode" : 12345, "more info": 
"http://dev.teachdogrest.com/errors/12345"}
In summary, be verbose and use plain language descriptions. Add as many hints as your 
API team can think of about what's causing an error. 
We highly recommend you add a link in your description to more information, like Twilio 
does. 
VB.NET PDF File Split Library: Split, seperate PDF into multiple
application. Divide PDF file into multiple files by outputting PDF file size. Split PDF document by PDF bookmark and outlines in VB.NET.
convert excel to pdf with bookmarks; create bookmarks pdf file
VB.NET PDF File Compress Library: Compress reduce PDF size in vb.
Also able to uncompress PDF file in VB.NET programs. Offer flexible and royalty-free developing library license for VB.NET programmers to compress PDF file.
pdf create bookmarks; create bookmarks in pdf
Web API Design - Crafting Interfaces that Developers Love 
13          
 
Tips for versioning  
Versioning is one of the most important considerations when designing your Web API.  
Never release an API without a version and make the version mandatory.  
Let's see how three top API providers handle versioning. 
Twilio  
/2010-04-01/Accounts/ 
salesforce.com 
/services/data/v20.0/sobjects/Account 
Facebook 
?v=1.0 
Twilio uses a timestamp in the URL (note the European format). 
At compilation time, the developer includes the timestamp of the application when the 
code was compiled. That timestamp goes in all the HTTP requests. 
When a request arrives, Twilio does a look up. Based on the timestamp they identify the 
API that was valid when this code was created and route accordingly. 
It's a very clever and interesting approach, although we think it is a bit complex. For 
example, it can be confusing to understand whether the timestamp is the compilation time 
or the timestamp when the API was released.  
Salesforce.com uses v20.0, placed somewhere in the middle of the URL. 
We like the use of the v. notation. However, we don't like using the .0 because it implies 
that the interface might be changing more frequently than it should. The logic behind an 
interface can change rapidly but the interface itself shouldn't change frequently. 
Facebook also uses the v. notation but makes the version an optional parameter. 
This is problematic because as soon as Facebook forced the API up to the next version, all 
the apps that didn't include the version number broke and had to be pulled back and 
version number added. 
C# PDF File Split Library: Split, seperate PDF into multiple files
defined pages. Divide PDF file into multiple files by outputting PDF file size. Split PDF document by PDF bookmark and outlines. Also
how to add bookmark in pdf; editing bookmarks in pdf
VB.NET PDF File Merge Library: Merge, append PDF files in vb.net
Professional VB.NET PDF file merging SDK support Visual Studio .NET. Merge PDF without size limitation. Append one PDF file to the end of another one in VB.NET.
pdf reader with bookmarks; add bookmark pdf
Web API Design - Crafting Interfaces that Developers Love 
14          
 
How to think about version numbers in a pragmatic way with REST? 
Never release an API without a version. Make the version mandatory. 
Specify the version with a 'v' prefix. Move it all the way to the left in the URL so that it has 
the highest scope (e.g. 
/v1/dogs
). 
Use a simple ordinal number. Don't use the dot notation like v1.2 because it implies a 
granularity of versioning that doesn't work well with APIs--it's an interface not an 
implementation. Stick with v1, v2, and so on. 
How many versions should you maintain? Maintain at least one version back. 
For how long should you maintain a version? Give developers at least one cycle to react 
before obsoleting a version. 
Sometimes that's 6 months; sometimes it’s 2 years. It depends on your developers' 
development platform, application type, and application users. For example, mobile apps 
take longer to rev’ than Web apps. 
Should version and format be in URLs or headers? 
There is a strong school of thought about putting format and version in the header. 
Sometimes people are forced to put the version in the header because they have multiple 
inter-dependent APIs. That is often a symptom of a bigger problem, namely, they are 
usually exposing their internal mess instead of creating one, usable API facade on top. 
That’s not to say that putting the version in the header is a symptom of a problematic API 
design. It's not! 
In fact, using headers is more correct for many reasons: it leverages existing HTTP 
standards, it's intellectually consistent with Fielding's vision, it solves some hard real-
world problems related to inter-dependent APIs, and more. 
However, we think the reason most of the popular APIs do not use it is because it's less fun 
to hack in a browser. 
Simple rules we follow: 
If it changes the logic you write to handle the response, put it in the URL so you can see it 
easily.  
If it doesn't change the logic for each response, like OAuth information, put it in the header. 
C# PDF File Merge Library: Merge, append PDF files in C#.net, ASP.
Professional C#.NET PDF SDK for merging PDF file merging in Visual Studio .NET. Append one PDF file to the end of another and save to a single PDF file.
pdf bookmark editor; bookmarks pdf file
C# PDF File Compress Library: Compress reduce PDF size in C#.net
Reduce image resources: Since images are usually or large size, images size reducing can help to reduce PDF file size effectively.
display bookmarks in pdf; bookmark pdf documents
Web API Design - Crafting Interfaces that Developers Love 
15          
 
These for example, all represent the same resource: 
dogs/1 
Content-Type: application/json 
dogs/1 
Content-Type: application/xml 
dogs/1 
Content-Type: application/png
The code we would write to handle the responses would be very different. 
There's no question the header is more correct and it is still a very strong API design. 
C# PDF Library SDK to view, edit, convert, process PDF file for C#
and quick navigation link in PDF bookmark. C#.NET: Edit PDF Metadata. PDF SDK for .NET allows you to read, add, edit, update, and delete PDF file metadata, like
add bookmarks to pdf file; bookmarks in pdf
VB.NET Create PDF from Excel Library to convert xlsx, xls to PDF
C#.NET PDF file & pages edit, C#.NET PDF pages extract, copy, paste, C#.NET rotate PDF pages, C#.NET search text in PDF, C#.NET edit PDF bookmark, C#.NET edit
excel print to pdf with bookmarks; excel hyperlink to pdf bookmark
Web API Design - Crafting Interfaces that Developers Love 
16          
 
Pagination and partial response 
Partial response allows you to give developers just the information they need. 
Take for example a request for a tweet on the Twitter API. You'll get much more than a 
typical twitter app often needs - including the name of person, the text of the tweet, a 
timestamp, how often the message was re-tweeted, and a lot of metadata.  
Let's look at how several leading APIs handle giving developers just what they need in 
responses, including Google who pioneered the idea of partial response. 
LinkedIn 
/people:(id,first-name,last-name,industry) 
This request on a person returns the ID, first name, last name, and the industry. 
LinkedIn does partial selection using this terse 
:(...)
syntax which isn't self-evident. 
Plus it's difficult for a developer to reverse engineer the meaning using a search engine.  
Facebook 
/joe.smith/friends?fields=id,name,picture 
Google 
?fields=title,media:group(media:thumbnail) 
Google and Facebook have a similar approach, which works well. 
They each have an optional parameter called fields after which you put the names of fields 
you want to be returned. 
As you see in this example, you can also put sub-objects in responses to pull in other 
information from additional resources. 
Add optional fields in a comma-delimited list 
The Google approach works extremely well. 
Here's how to get just the information we need from our dogs API using this approach: 
/dogs?fields=name,color,location 
It's simple to read; a developer can select just the information an app needs at a given time; 
it cuts down on bandwidth issues, which is important for mobile apps. 
Web API Design - Crafting Interfaces that Developers Love 
17          
 
The partial selection syntax can also be used to include associated resources cutting down 
on the number of requests needed to get the required information. 
Make it easy for developers to paginate objects in a database 
It's almost always a bad idea to return every resource in a database. 
Let's look at how Facebook, Twitter, and LinkedIn handle pagination. Facebook uses offset 
and limit. Twitter uses page and rpp (records per page). LinkedIn uses start and count 
Semantically, Facebook and LinkedIn do the same thing. That is, the LinkedIn start & count 
is used in the same way as the Facebook offset & limit. 
To get records 50 through 75 from each system, you would use: 
Facebook - offset 50 and limit 25 
Twitter - page 3 and rpp 25 (records per page) 
LinkedIn - start 50 and count 25 
Use limit and offset 
We recommend limit and offset. It is more common, well understood in leading databases, 
and easy for developers. 
/dogs?limit=25&offset=50 
Metadata 
We also suggest including metadata with each response that is paginated that indicated to 
the developer the total number of records available. 
What about defaults? 
My loose rule of thumb for default pagination is limit=10 with offset=0. 
(
limit=10&offset=0
The pagination defaults are of course dependent on your data size. If your resources are 
large, you probably want to limit it to fewer than 10; if resources are small, it can make 
sense to choose a larger limit. 
Web API Design - Crafting Interfaces that Developers Love 
18          
 
In summary: 
Support partial response by adding optional fields in a comma delimited list. 
Use limit and offset to make it easy for developers to paginate objects. 
Web API Design - Crafting Interfaces that Developers Love 
19          
 
What about responses that don’t involve resources? 
API calls that send a response that's not a resource per se are not uncommon depending on 
the domain. We've seen it in financial services, Telco, and the automotive domain to some 
extent. 
Actions like the following are your clue that you might not be dealing with a "resource" 
response. 
Calculate 
Translate 
Convert 
For example, you want to make a simple algorithmic calculation like how much tax 
someone should pay, or do a natural language translation (one language in request; 
another in response), or convert one currency to another. None involve resources returned 
from a database. 
In these cases: 
Use verbs not nouns  
For example, an API to convert 100 euros to Chinese Yen: 
/convert?from=EUR&to=CNY&amount=100 
Make it clear in your API documentation that these “non-resource” scenarios are 
different.  
Simply separate out a section of documentation that makes it clear that you use verbs in 
cases like this – where some action is taken to generate or calculate the response, rather 
than returning a resource directly. 
Web API Design - Crafting Interfaces that Developers Love 
20          
 
Supporting multiple formats  
We recommend that you support more than one format - that you push things out in one 
format and accept as many formats as necessary. You can usually automate the mapping 
from format to format. 
Here's what the syntax looks like for a few key APIs. 
Google Data 
?alt=json 
Foursquare 
/venue.json 
Digg* 
Accept: application/json 
?type=json 
* The type argument, if present, overrides the 
Accept
header. 
Digg allows you to specify in two ways: in a pure RESTful way in the Accept header or in 
the type parameter in the URL. This can be confusing - at the very least you need to 
document what to do if there are conflicts. 
We recommend the Foursquare approach. 
To get the JSON format from a collection or specific element: 
dogs.json 
/dogs/1234.json 
Developers and even casual users of any file system are familiar to this dot notation. It also 
requires just one additional character (the period) to get the point across. 
What about default formats? 
In my opinion, JSON is winning out as the default format. JSON is the closest thing we have 
to universal language. Even if the back end is built in Ruby on Rails, PHP, Java, Python etc., 
most projects probably touch JavaScript for the front-end. It also has the advantage of being 
terse - less verbose than XML. 
Documents you may be interested
Documents you may be interested