Aspects of the APIs Based on Standard API Principles - Report Example

?INTRODUCTION According to Hans-Christian Jetter, application programming interfaces (APIs) are the interfaces to existing structures, such as widgets, frameworks, or toolkits. Therefore, they very much do have an impact on the quality of the resulting system. So ensuring that developers can make the most out of them is an important challenge(Jetter ,2011). According to apievangelist, an API allows your product to talk to other products or services. An API allows one to open data and functionality to other developers and businesses(What is an API,apievangelist, n.d). An API allows a developer’s product or service to communicate to other products and services. APIs open up data and functionality to other developers and to businesses. It allows exchange of data both internally and externally.(Jetter,2011) According to apievangelist, an API gives third party developers “firewall” access to a company’s data and resources.(apievangelist n.d) TWITTER API Twitter is an information network and communication mechanism that produces more than 200 million tweets a day. The Twitter API is largely used by majority of developers to extend twitters social experience and functionality to their own applications. Twitter offers access to its data through use of its APIs. Twitter offers products for websites that easily integrates basic twitter functions for example the tweet button. Twitter also offers a search API for developers who want to allow a user to query for twitter content. The streaming API offered by twitter provides a real time sample of the twitter firehose. It is for developers with data intensive needs for example a data mining project. The twitter REST API enables the developer to access core primitives of twitter including timelines status updates and user information. LINKEDIN API LinkedIn is a social network for professionals and business people. According to LinkedIn, their API enables developers to provide an easy way of enabling professionals to sign in their site using LinkedIn credentials. It also enables engagement by bringing professional content to the developer’s site. It also enables powerful conversations through its provisional groups API.(Why develop with LinkedIn, n.d) PURPOSE OF REPORT This is an evaluation report containing a critical evaluation of three third party API’s. It evaluates and discusses each and every aspect of the APIs based on standard API principles. The third API is provided to contrast with the two mentioned APIs. The report aims to find the most suitable and most efficient API from the three for better development using APIs and their integration. AUTHENTICATION Authentication is the process of identifying user provided credentials and authorizing access to an applications functionality. This is a common feature found in most applications. A huge number of users have signed up with popular web applications including Twitter and LinkedIn. Due to the problem of creating separate and multiple user credentials combination of passwords and names, developers have turned to using this functionality from the mentioned applications. These applications provide authentication API’s that make it easier for the developer to rapidly integrate the functionality in their application . The authentication API also provides for extended feature sets and secure authentication and authorization for the developers application which all in all is beneficial to everyone. Twitter provides several variations of the authentication API for developers through the rest API version 1.1 Authentication using the Twitter API uses the OAuth authentication styles. The developer should choose the method of authentication. Twitter offers different flavours for authentication. These include the rest API for authentication, Search API for authentication and streaming API for authentication. Each of them has specific way of implementing Twitter’s OAuth authentication(Authentication and authorization,Twitter n.d). For the OAuth signed in option the developer must obtain OAuth access token for their application. Implementation of the Twitter sign up According to twitter, the authentication flow for the application must start by obtaining a request token by sending a signed message to POST OAuth/request_token.The token has parameters which must be a url encoded version of the url,other parameters are added by the OAuth signing process The twitter authentication flow chart (authentication flow,Twitter,n.d) describes the signup and signin flow for a user. Fig 1.0 Twitter authentication flow Authentication flowchart, Twitter developers(n.d) Authentication and authorization[online] Available at:dev.twitter.com/docs/auth [Accessed:14 Apr 2013]. Twitter goes on to explain that the application should examine the HTTP status of the response.The body of the response should contain the oauth_token,oauth_token_secret and oauth_callback_confirmed parameters.The application should verify the OAuth callback is true and store the other two values.(twitter authentication documentation).The API offers a direct to the user to GET OAuth/authenticate and the request token obtained previously. Most desktop apps and mobile apps should open a new browser window or direct to the url via an embedded web view(twitter documentation). Fig 1.1 redirecting of the user Redirect flow chart,Authentication,Twitter developers(n.d) Authentication and authorization[online] Available at: dev.twitter.com/docs/auth [Accessed:14 Apr 2013]. The redirect flowchart(Twitter) describes the redirect flow for a user after signin or signup. The sign in endpoint behaves in one of the three ways depending on the user’s status. The user may be signed in and approved. If so the user is immediately authenticated and returned to the callback URL with a valid Oauth request token. The redirect is not obvious. The user status might be signed in and not approved. Here the user is requested to share access with the application using the api. After authorization, the user is redirected to the callback URL with valid OAuth request token. The user status might be not signed in. If not signed in, they will be requested to enter their credentials and grant access to their twitter data. Once signed in the user will be returned to the callback URL with valid OAuth request token. Fig 1.2 users status User flowchart image, Twitter developers(n.d) Authentication and authorization[online] Available at:dev.twitter.com/docs/auth [Accessed:14 Apr 2013]. The User status flow chart(twitter n.d) above describes the user status during each signin condition. LinkedIn Authentication LinkedIn also has an authentication feature based on its REST API. LinkedIn offers a procedural step by step process for user authentication. LinkedIn requests the developers to register their application with LinkedIn. LinkedIn provides them with an API key and secret key which are unique and should be kept private. These are OAuth keys. The developers then get an access token which is unique to a user and an API key(Oauth LinkedIn n.d).According to the LinkedIn documentation the access keys make API calls to LinkedIn on behalf of the user who authorized the developers application. Fig 1.3 LinkedIn redirect Redirect Code sample,Authorization, LinkedIn developers(n.d) Authentication and authorization[online] Available at: developers.linkedin.com/auth [Accessed:14 Apr 2013]. The code sample image above(linkedIn) shows the code for redirecting a user. The user is redirected to the specified redirect_url with a temporary authorization code. According to LinkedIn, access tokens generated for a user have a life span of 60 days. There should be a mechanism to refresh the tokens before they expire or a user has to go through authorization steps again.(LinkedIn documentation n.d). A developer can also grant users permissions within their applications. Fig 1.4 LinkedIn login view Dialog box for LinkedIn, Authentication, LinkedIn developers(n.d) Authentication[online] Available at: developer.linkedIn.com/documents/authentication[Accessed: 14 Apr 2013]. The above image is the dialog box presented to users(LinkedIn dialog box n.d). Third API There is no clear authentication and authorization flow. Comparisons of the authentication APIs Twitter offers a more comprehensive and fully featured authentications system as compared to LinkedIn. It provides more feature sets and extended functionality and variation in the user authentication process. The third API has minimal offers. Twitter API is therefore the best and is easy to adapt to and provides more features. RATE LIMITING This is a consideration by the API on a per user basis or according to twitter documentation, a per access token in the developers control(REST API rate limiting documentation,Twitter n.d). Twitter rate limiting Rate limiting in version 1.1 of the twitter REST API offers rate limits of up to 15 minute intervals, a change from the previous 60 minute interval rating(rate limiting Twitter n.d).Twitter uses new HTTP headers that provide data on where the application is at for a given rate limit. According to twitter documentation on rate limiting, the HTTP headers indicate the rate limit for the application context. When an application exceeds the rate limit for a given API endpoint, the twitter API returns an HTTP 429 which shows too many requests error message. The body of the HTTP 429 message is shown below Code sample, REST API rate limiting, Twitter developers(n.d) REST API rate limiting[online] Available at:dev.twitter.com/docs/rate-limiting/1.1[Accessed:14 Apr 2013]. The above picture shows a code sample for rate-limiting. According to twitters rate limiting documentation, there are times in which the rate limit values returned by the API are inconsistent or where no headers are returned at all. In these situations the memcache might have been reset or they are busy.(API documentation Twitter n.d). Twitter offers tips to avoid being rate limited. These include caching, prioritizing active users, adapting the search results, using the application-only auth as a reserve and blacklisting. LinkedIn Rate limiting LinkedIn provides a “throttle limiting” (Throttle Limiting,LinkedIn n.d ) on its API which is the same as rate limiting. According to the throttle limiting on LinkedIn, there is a provision for three types of limiting for all API keys. These include the application throttles, user throttles and developer throttles. The application throttle works by limiting number of each API call on the developers application. User throttles limit the number of calls for any individual user of the developers application(LinkedIn throttle limiting documentation).Developer throttles are for giving the developer extra capacity to build and test their application. LinkedIn provides throttle http responses to the developer. The code sample shows the 403 HTTP status code with a response body (HTTP responses,LinkedIn n.d). Throttle limits, LinkedIn developers(n.d) Throttle limiting[online] Available at:developer.linkedin.com/documents/throttle-limits[Accessed: 14 Apr 2013]. The above is an xml code sample that illustrates how throttle limiting works in LinkedIn(Throttle limiting,LinkedIn n.d). LinkedIn provides different calls for throttle limiting. These include : calls for the users own data, calls for the users network data, calls for the users network data, calls for the users group data and calls for jobs and company data. Third API rate limiting There is no clear documentation provided on rate limiting for the third API. Comparison of rate limiting The rate limiting variations between the APIs provided are huge. Rate limiting on LinkedIn is not outlined in detail as it is on twitter documentation. Throttle limiting on the LinkedIn API is quite comprehensive and elaborate for a developers ease of understanding and use. The third API does not feature a clear set rate limiting factor as compared to the other two. Twitter API henceforth is the better API in terms of rate limiting provisions for applications that require social data and LinkedIn API is more suitable for business applications. TERMS OF SERVICE The terms of service are rules by which the developers are bound in use of the API provided by these existing applications. They determine the legal bounds and use of the API. They spell out the necessary boundaries to the use of content obtained from the applications. They enforce the privacy of user data. For the terms of service they should be evolving and relevant at all times. Twitter terms of service Twitter offers developers an elaborate terms of service. They spell out how there platform works, who it supports and the balance between encouraging development and protecting both their rights and users rights (Terms of service,Twitter,n.d). According to the Twitter terms, all developers are subject to the rules of using twitter content. Twitter content includes the twitter API, documentation, code and service provided by the developer to the users. Developers have a list of restrictions that are described clearly in the terms of service. These restrictions include not selling or renting or giving access to the twitter API to third parties, developers should not remove or alter any proprietary notices on the Twitter API.They must use the twitter API as provided by twitter for functionalities in the developers service. Developers have a set of principles by which they should operate. This include not surprising users, not creating or distributing spam, respecting the users privacy and being a good partner to twitter. The developer’s service should not use business names or logos that mislead or deceive users. The twitter terms go on to describe the legal twitter functionality in the developers service and commercial use whereby twitter states that the developer should respect user content and respect of the user experience. Twitter terms of service also provides grounds for termination, confidentiality, ownership, updates on the twitter API and a disclaimer for the API service. LinkedIn terms of service The LinkedIn terms provides approved legal membership of developers by allowing them to create developer accounts and access credentials for the developers credentials. The terms restrict developers from selling transferring or sublicensing their accounts. They also explicitly explain the terms on the API license. Developers are encouraged to act professionally by displaying and using content properly. LinkedIn terms also excludes uses of the data obtained from their network such as using LinkedIn content for advertisements. Developers should store content only as allowed, no copying and are allowed to store the user tokens as provided. Developers should also follow the law as depicted in the extra terms of service provided for by LinkedIn. These involve the linked user agreement, linked privacy policy, platform guidelines and branding guidelines. The LinkedIn terms of service also provides grounds for safety and abuse. They detail the safety measures and security measures. LinkedIn also reserves some rights which include modification o f the API,fees charged for their services and LinkedIn independent development. Linked in also reserves its own proprietary rights. They provide legal grounds for termination and also warranty disclaimer for use of their API. Third API terms of service The third API offers no visible legal terms of service for its use. Comparison of terms of service Twitter terms of service provide the best terms for any developer as compared to LinkedIn and the third API. The third API offers no legal terms and therefore cannot be compared. Linkedin terms of services are while definitive and clear, do not offer well provisioned and consistently evolving terms of service as the twitter terms. VERSIONING According to George Reese, versioning is a critical component of an API to prevent those third party tools from breaking(Reese, 2010).this definitely means the evolution of the API through changes and improvements on the existing API. Twitter API versioning. Twitter has currently has moved to its newer version REST API version 1.1 from its older version 1.According to the twitter documentation, the REST API version 1 is deprecated and will not function and are advising their developers to move to the most recent version 1.1. LinkedIn API versions LinkedIn has maintained one version of their current REST API. Third API version There is no clear indication of versions for the third api. Comparison of versioning Twitter maintains a constantly improving REST API. It is therefore better compared to the other two APIs as it ensures provision of consistent and ever improving functionality which provides a developer with peace of mind after migration from a deprecated version. HTTP STATUS CODES The http status codes are codes that display an error to the developer and user of an application that has extended API functionality. The API providers use HTTP status codes which are more or less the same to show error messages, response messages and success messages. Twitter API status codes The twitter API status codes include error messages, error codes and http responses. According to the Twitter documentation the error messages are delivered in a requested format. The diagram below shows an error message in JSON format. HTTP response codes, Documentation, Twitter developers(n.d) HTTP codes[online] Available at: dev.twitter.com/docs/streaming-api-response-codes[Accessed: 14 Apr 2013]. The above image displays an http error message(error message,Twitter n.d). Example list of the universal API http status codes CODE TEXT DESCRIPTION 200 OK Success! 304 Not modified There was no new data 400 Bad request The request was invalid 32 Could not authenticate you call could not be completed The above table is a depiction of the status codes of an API(HTTP status codes,twitter and linkedIn). LinkedIn API status codes The more common http status codes used by LinkedIn are also used in twitter. Third API status codes The third API offers no http status codes. Comparison of http status codes The third API has no reference to http status codes. HTTP status codes are more or less the same. Twitter though according to their status code documentation have extended http status codes which are clearly defined as error codes in its code listing. Twitter API is more suitable for developers due to this fact as it offers more specific response messages for what might have gone wrong with the application. CACHING Twitter API Twitter encourages the storage of the API responses in the developer’s application, to improve performance in case of huge traffic to the application. The application hence loads the response of the API into a local cache instead of calling the Twitter API on every page load of the developer’s website or application. LinkedIn API According to the terms of use on LinkedIn ,a developer may not store or cache any content returned through the LinkedIn API, this includes data about users. Attempting storage results in breach of terms and leads to termination.(LinkedIn terms of use). Third API The third API offers no referral documentation in caching via its API Comparison of caching Caching is very important in that it reduces the number of calls to the API and increases performance of the developers application .Due to terms of service offered by the LinkedIn social network, storage or caching is not allowed. The third API offers no caching documentation. Hence twitter API is the best option for developers to integrate and extend their applications as it offers caching with via its Search API. DOCUMENTATION Twitter API documentation Twitter offers a comprehensive documentation for its API for developers. It offers a field guide to its twitter platform objects. The objects are shown below A field guide to Twitter objects, image by twitter, Twitter developers(n.d) Guide to Twitter platform objects[online] Available at: dev.twitter.com/docs/platform-objects[Accessed:14Apr 2013]. The above diagram is a depiction of the twitter field objects(field objects,Twitter). It enlists the twitter extension functionalities that may be added to a developers website. These include twitter cards,twitter platform on mobile, embedded timelines, embedded tweets and twitter buttons.It offers guidelines and terms of service and use for developers. Twitter documentation contains reference to the REST API which acts as a simple interface for most twitter functionality, the streaming APIs which offer real time APIs for tweets and other social events. Twitter also has documentation that helps businesses find the best products and services (dev.twitter.com).This is through the twitter certified product program. LinkedIn API documentation LinkedIn has full documentation for its API. They provide an overview of what the API contains. The LinkedIn API includes people authentication and authorization. The share and social stream for seamless integration of content distribution. It has implementation documentation for enabling communication within the networks and via the API. LinkedIn documentation offers two implementations for its API, that is through the REST API and Javascript API implementations. Third API documentation There is no documentation for the third API. Comparison of documentation Twitter and LinkedIn provide good resources for its developers. The documentation detail and specify how to use the API implementations and also provide legal policies on how to operate within the platform. For practical purposes and contexts, each documentation satisfies its purpose of guiding a developer through its features and objects hence enabling successful extension of their application with powerful features from these APIs. The third API has no documentation and it is thus up to the developer to read through the JSON implementation, therefore rendering it unlikely to be used. CONCLUSION The evaluation of the three APIs reveals how they work. Based on the standards discussed in this report, the overall conclusion is that with each API there is a performance bottleneck. Each API is used within its own context and has features that suite a particular type of application than the other. Hence the APIs are on per in those terms. However the Twitter API is by far more advanced and well documented than the other two APIs. BIBLIOGRAPHY A field guide to Twitter Platform objects, Twitter developers(n.d) Guide to Twitter platform objects[online] Available at: dev.twitter.com/docs/platform-objects[Accessed: 14 Apr 2013]. A field guide to Twitter objects, image by twitter, Twitter developers(n.d) Guide to Twitter platform objects[online] Available at: dev.twitter.com/docs/platform-objects[Accessed:14Apr 2013]. Authentication and authorization, Twitter developers(n.d) Authentication and authorization[online] Available at: dev.twitter.com/docs/auth[Accessed: 14 Apr 2013]. Authentication flowchart, Twitter developers(n.d) Authentication and authorization[online] Available at:dev.twitter.com/docs/auth [Accessed:14 Apr 2013]. API overview, LinkedIn developers(n.d) API overview[online] Available at:developer.linkedin.com/apis[Accessed:14 Apr 2013]. Authentication, LinkedIn developers(n.d) Authentication[online] Available at:developer.linkedin.com/documents/authentication [Accessed: 14 Apr 2013]. Code sample, REST API rate limiting, Twitter developers(n.d) REST API rate limiting[online] Available at:dev.twitter.com/docs/rate-limiting/1.1[Accessed:14 Apr 2013]. Developer rules of the road, Twitter developers(n.d) Developer rules[online] Available at:dev.twitter.com/terms/apit-terms[Accessed: 14 Apr 2013]. Dialog box for LinkedIn, Authentication, LinkedIn developers(n.d) Authentication[online] Available at: developer.linkedIn.com/documents/authentication[Accessed: 14 Apr 2013]. Documentation twitter, Documentation, twitter developers(n.d) Documentation[online] Available at : dev.twitter.com/docs [Accessed: 14 Apr 2013]. Hans-Christian Jetter, Jens Gerken,et al P. (2006), “The concept maps method as a tool to evaluate the usability of APIs”, University of Konstanz HCI group. HTTP response codes, Documentation, Twitter developers(n.d) HTTP codes[online] Available at: dev.twitter.com/docs/httpresponses[Accessed: 14 Apr 2013]. HTTP error message image, Documentation, Twitter developers(n.d) HTTP codes[online] Available at: dev.twitter.com/docs/streaming-api-response-codes[Accessed: 14 Apr 2013]. Javascript, LinkedIn developers(n.d) JavaScript[online] Available at:developer.linkedin.com/javascript[Accessed: 14 Apr 2013]. LinkedIn APIs Terms of use,LinkedIn developers(n.d) Terms of use[online] Available at: developer.linkedin.com/documents/linkedin-apis-terms-of-use[Accessed: 14 Apr 2013]. LinkedIn policies,LinkedIn developers(n.d) Policies[online] Available at: developer.linkedin.com/linkedin-policies[Accessed: 14 Apr 2013]. Oreilly community,API versioning, George Reese (October 12,2011) API versioning[online] Available at:broadcast.oreilly.com/2011/10/api-versioning.html [Accessed: 14 Apr 2013]. Redirect flow chart,Authentication,Twitter developers(n.d) Authentication and authorization[online] Available at: dev.twitter.com/docs/auth [Accessed:14 Apr 2013]. REST API v1.1 Resources, REST API, Twitter developers(n.d) REST API v1.1[online] Available at: dev.twitter.com/docs/api/1.1 [Accessed: 14 Apr 2013]. REST API rate limiting, Twitter developers(n.d) REST API rate limiting[online] Available at:dev.twitter.com/docs/rate-limiting/1.1[Accessed:14 Apr 2013]. REST, LinkedIn developers (n.d) REST[online] Available at:developer.linkedin.com/rest[Accessed:14 Apr 2013]. Simple API client, My ASP.NET application(n.d) Welcome to simple API client[online] Available at:fostvm.fost.plymouth.ac.uk/softt338/VMoorti[Accessed: 14 Apr 2013]. The streaming APIs,StreamingAPIs,Twitter developers(n.d) Streaming API[online]Available at: dev.twitter.com/docs/streaming-apis [Accessed: 14 Apr 2013]. Twitter for websites,Twitter developers(n.d) Twitter for websites[online] Available at: dev.twitter.com/docs/twitter-for-websites[Accessed:14Apr 2013]. Throttle limits, LinkedIn developers(n.d) Throttle limiting[online] Available at:developer.linkedin.com/documents/throttle-limits[Accessed: 14 Apr 2013]. User flowchart image, Twitter developers(n.d) Authentication and authorization[online] Available at:dev.twitter.com/docs/auth [Accessed:14 Apr 2013]. What is an API,API evangelist,(n.d) API[online] Available at: apievangelist.com[Accessed: 14 Apr 2013]. Read More