Contents

Designing an API, Tips & Tricks

Pacewisdom
,
Nov 8th, 2017
0
min read

Application Programming Interface (API), Effective and Productive Designing, Tips & Tricks

In the era of Internet, an application is being developed for each and every aspect that is useful to us. Application Programming Interface (API) acts as a bridge between the user and the application developer.  From the user point of view, an application must be useful for a long period of time. API’s once designed cannot be changed however; we could provide an option to upgrade the API or technically speaking extension.An effective and productive design of an API requires short term and long term planning. Short term would be the code for immediate requirement and long term would be providing options for extension.

A few tips and tricks will be discussed here to make it easier to build an effective API using least resources and achieving maximum results.

Restful method-Prioritizing noun resources over verb ones.

You could use noun resources instead of verb resources to avoid the result in a huge list of URLs. This would be a burden on the developer and the user to search for a particular file or document.  An API needs to be user friendly and provide room for experimenting successfully with the URLs.

The perfect solution for this issue would be using the noun resources.

GET(read) offers two options which are: return list of all files and a specific file.

POST(create) offers two options which is are: add a new file and an error(since there wouldn’t be anything stored in the application without the user adding it).

PUT(Update) offers two options which are: bulk update of all files and update a specific file.

DELETE(delete) offers two options which are: delete all files and delete a specific file.

You could use /files and /file/:id in conjunction with GET, POST, PUT and DELETE to perform operations even if a huge list has been generated.

Transformers for data representation

Transformers, as the name suggests transforms data from one format to another. There are many reasons out of which the most prominent ones would be, control over data you actually output to consumers and prohibit any sensitive information being displayed accidentally.

The benefit of serializing the data as per your requirement and embed related resources within each other is offered by using transformers.

Handling Errors

The easiest way to handle errors would be using HTTP status codes which are pretty much self explanatory.

200 Successful

201 Resource creation successful

204 Successful but no content returned

304 Request not modified

400 Bad request

401 Unauthorized, needs authentication

403 Forbidden

401 Conflict with the current state

Knowing the error code will help pinpoint the issue in the code for resolving it.

Documentation

Documenting your work is a crucial part for an API. Documentation involves a few steps to be followed to make your API productive.

  • Resource URL and information
  • https://design.api.com/file/:id and requires authentication.
  • Parameters
  • Specify mandatory and optional ones.
  • Example request and result
  • Authentication
  • Two steps more in authentication. Basic and 0Auth2 which is your username and password and access token to access the API resource respectively.

TECH TALK
APPLICATION
API
PROGRAMMING INTERFACE
web development

Pacewisdom Solutions Blog

Our vision is to drive to business outcomes at an accelerated pace by delivering next generation software solutions and end-to-end technology advisory services. Since our inception in 2012, we have delivered over 150 cutting edge solutions across the 10 countries spanning several industry verticals. We remain focused on creating sustainable value for our customers by reinventing our offerings to take advantage of advancement in technologies as well as adapt to industry trends.
Visit Site

From Product Engineering to Optimising your cloud bills.

Pacewisdom is your go to for anything technology.
Book An Appointment