Click me

Infographic 10 Key Principals Of Successful API Design

NNODE1 10 KEY PRINCIPALS OF SUCCESSFUL API DESIGN Today a key strateglc conslderatlon for forward-looking buslnesses and publlc authorltles Is Innovatlon. The most pervaslve driver of Innovatlon Is IT. IT Innovatlons are catalysts for Innovatlon In every other domaln. Moreover, IT provldes us the opportunity to tap Into the holy grall of network effects at exceedingly low transactlon costs. As such It provldes us the leverage to disrupt vertical markets and bulld ecosystems around our buslness. Software Is eating the world. As the digltal glue of an Increasingly connected world API's are In thelr turn the great enabler of IT Innovatlon. As Steven WIllmott, CEO of 3Scale, polnts out 'If software Is eating the world than API's are eating software. Because of the Importance of API's here are 10 Key API Design PrInclples. These API deslgn princlpals are based on Input from the API Web Deslgn E-book Crafting Interfaces Developers Aplgee Labs, LIcensed under CC BY-SA 3.0. Please find the E-book on ve, by Brlan Mulloy, vlce presldent of DESIGN FROM THE KEEP IT SIMPLE DEVELOPER'S PERSPECTIVE 1 Maybe the most important reason to expose business assets through an API is to tap into the creative power of the masses. In the end it's the developers, internally and/or externally, that are going to develop the apps your customers (end users) are going to use. A golden and universal design rule is to keep things simple. This also counts for API design. It should be exceedingly simple for developers to use your API. In this regard a simple and intuitive base URL of your API is fundamental. After all the base URL is the most important design affordance of your API. Therefore, when building an API your primary design axiom should be to maximize developer success. As mentioned in a previous blog post it's not important what API you create, but what it enables developers to create. Keep verbs out your base URL and use HTTP verbs (GET, POST, PUT, DELETE) to collections and elements. opera Remember the words of the pioneering French aviator Antoine de Saint Exupéry's: "It seems that perfection is reached not when there is nothing left to add, but when there is nothing left to take away" DON'T FORGET APIS CHANGE, 3 ERROR HANDLING SO RELEASE VERSIONS If there is one thing true about your API it's that it will change. Bugs need to be fixed, security holes closed, out-of-date schemas updated. Typically errors only account for a fraction of all messages sent by the API. However, they are the most scrutinized messages by app developers, because developers simply make errors. To prevent developers abandoning your API it's important to make it as easy as possible for them to use your API. There are many error handling measures you can consider but in our opinion the most important ones are: On the other hand it's a guarantee for failure if you make such dramatic changes to an API that is already in use that it crashes. By versioning your API you can make changes without breaking already-existing implementations. The latter is the key deter- minant for whether or not a new version is Use a limited number of common HTTP status codes Set Location Provide a Help URL Use plain – human readable – error imperative. You should consider only a new version if the change in funtionality will break current implementations. SUPPORT PARTIAL SUPPORT MULTIPLE RESPONSE RESPONSE TYPES Google introduced partial response in 2010, almost 4 years ago. By supporting partial response only a subset of information can be transferred. Partial reponse is about improving efficiency and eliminating redundancy. You cannot assume that developers will use only the response type you prefer. Therefore use more than one format and accept as many formats as necessary. Less data transferred over the network means less bandwidth usage, faster server response, less CPU time spent on the server and client side, as well as less memory usage on the Supporting XML, JSON, PHP, and others is not much more work and yet has a measur- able impact on your APIS adoption. Use JSON as your default response type. 6. client side. You can suport partial response by adding optional fields in a comma delimited list. PROVIDE SHORTCUTS IMPLEMENT THE OR COMPOSITE RESPONSES API FAÇADE PATTERN APIS should be very simple and easy to use. Ease of use also implies granularity: devel- opers can get exactly the data that they need, not more. 7 It cannot be said often enough: simplicity is key to API adoption by developers and therefore API success. The downside of granularity is the 'chatti- ness' of the API. Chatty apps are constantly making data requests and because applica- tion processes are often dependent on each other, each call has to wait for the preceding call to return data first. One measure to improve API adoption is to implement the API Façade Pattern. This is because the back-end of your internal systems of record are often too complex to expose directly to developers. The API Façade Pattern enables you to break down the complexity of your system in 'digestible' or less complex subsystems or problems. This problem can be mitigated by providing shortcuts or composite responses if needed. BUILD A DEDICATED PROVIDE A SDK API PORTAL Complement the API with code samples, libraries and software development kits. Consolidate all API requests under one API subdomain for the sake of ease of use. The SDK will help to reduce bad or inefficient code and market the API to different devel- oper communities. 10 NNODE 1 www.NODE1.COM 8 91

Infographic 10 Key Principals Of Successful API Design

shared by samirsaberi on Feb 03
2 share
A description of 10 key principals for successful API design




Did you work on this visual? Claim credit!

Get a Quote

Embed Code

For hosted site:

Click the code to copy


Click the code to copy
Customize size