Divergent Techvolution: How APIs Fulfill the Original Promise of Service-Oriented Architecture

What is an API?

An API is a software intermediary that allows two applications to talk to each other. In other words, an API is the messenger that delivers your request to the provider that you’re requesting it from and then delivers the response back to you.

API(Application Programming Interface) is a set of instructions, standards or requirements that enables a software or app employ features/services of another app, platform or device for better services. In short, it’s something that let apps communicate with each other.

For example, when we hit on the ‘Connect Facebook’ button on Candy Crush, it does not ask us to enter our Facebook account details. Rather, it accesses the data from the Facebook server and let us enjoy playing — all thanks to API.

An API is the base of all the apps that deal with data or enable communication between two products or services. It empowers a mobile application or platform to share its data with other apps/platforms and ease the user experience without involving the developers. On the top of it, APIs eliminate the need to build a similar program or platform from scratch; you can use the existing one of some other app/platform. Because of these factors, both app developers and business leaders focus on API development.

An API defines functionalities that are independent of their respective implementations, which allows those implementations and definitions to vary without compromising each other. Therefore, a good API makes it easier to develop a program by providing the building blocks.

When developers create code, they don’t often start from scratch. APIs enable developers make repetitive yet complex processes highly reusable with a little bit of code. The speed that APIs enable developers to build out apps is crucial to the current pace of application development.

Developers are now much more productive than they were before when they had to write a lot of code from scratch. With an API they don’t have to reinvent the wheel every time they write a new program. Instead, they can focus on the unique proposition of their applications while outsourcing all of the commodity functionality to APIs.

The principle of API abstraction enables speed and agility

One of the chief advantages of APIs is that they allow the abstraction of functionality between one system and another. An API endpoint decouples the consuming application from the infrastructure that provides a service. As long as the specification for what the service provider is delivering to the endpoint remains unchanged, the alterations to the infrastructure behind the endpoint should not be noticed by the applications that rely on that API.

Therefore, the service provider is given a great deal of flexibility when it comes to how its services are offered. For example, if the infrastructure behind the API involves physical servers at a data center, the service provider can easily switch to virtual servers that run in the cloud.

If the software running on those servers (such as credit card processing software) is written in, say, Java running on an Oracle-based Java application server, the service provider can migrate that to Node.js (server-side Javascript) running on Windows Azure.

The ability of API-led connectivity to allow systems to change as easily as plugging in a plug to a socket is key to the modern vision of enterprise IT. Gone are the days of messy point-to-point integrations for connecting enterprise solutions which take time and resources to maintain.


a) API Key: When an API request through a header or parameter to recognize the requester, the authorized code passed into the request is said to be an API Key.

b) Endpoint: When an API interacts with another system, one end of the communication channel is termed as Endpoint.

c) JSON: JavaScript Object Notion or JSON is said to be a data format used for APIs request parameters and response body.

d) GET: The RESTful API’s HTTP method of obtaining resources is called GET.

e) POST: It is the RESTful API’s HTTP method for building resources.

f) OAuth: It is basically an Open standard authorization framework that renders access from the user’s side without directly sharing the credentials.

g) REST: REST (Representational State Transfer) is a kind of programming architectural implementation meant to enhance the efficiency of communication between the two devices/systems. It is light-weighted and based on the idea of making a particular data available only when requested by sharing references to the data instead of the entire copy of the data itself. The systems enforced on this architecture are said to be ‘RESTful’ systems, and the most overwhelming example of RESTful systems is the World Wide Web.

h) SOAP: SOAP or Simple Object Access Protocol is a messaging protocol for sharing structured information in the execution of web services in computer networks. It works with XML information set and application layer protocols (like HTTP and SMTP) for message format and message negotiation & transmission, respectively.

i) Latency: Latency is defined as the total time taken by an API in the process from the request to the response.

j) Rate-Limiting: The term API Rate-limiting refers to the process of defining the rate at which an end user can access the APIs. In other words, it means restricting the number of requests a user can hit to an API per time.

k) API Throttling: The process of regulating the usage of APIs by users during a particular time period is called Throttling. This can be used for API limiting. For example, you set the limit of 1000 API requests per day. When the user hit the 1001 request, the server will send 429 messages as HTTP status to the end user along with the message, “Too many Requests”.

For more terminology and acronym, refer this site.

Now, as you know what are APIs, are armed with the terminologies and are familiar with the anatomy of the growing API market, let’s dig deeper into the technical part — beginning with how do APIs work?

Working of API

Suppose you opened some XYZ app/website to book a flight. You filled the form — you entered the departure and return date, city, flight, and other relevant details — and submitted. With a fraction of seconds, a list of flights appears on the screen along with the price, timings, seat availability, and other details. How this actually happens?

To provide such stringent data, the platform sent a request to the airline’s website to access their database and get relevant data via API. The website responded with the data which API delivered to the platform and the platform displayed it on the screen.

Here, the flight booking app/platform and airline’s website act as endpoints while API as the intermediate streamlining the data sharing process. When talking about communicating the endpoints, the API works in two ways, namely: REST and SOAP (see definition above).

Though both the methods bring effective results, mobile app development companies prefer REST over SOAP since SOAP APIs are heavy and platform-dependent.

Now coming to the main part — How to develop an API? What tools and technologies to choose? What practices to adopt for an effective API development?

Tools for Developing an API ( like a PRO… Like Jay Dwayne Lol! )

While there are a plethora of tools and technologies equipped into the process of creating an API, the popular tools and products for developing APIs for developers are:

a) Apigee: It is a Google’s API management provider that assists the developers and entrepreneurs to triumph at digital transformation by reestablishing towards an API approach.

b) APIMatic and API Transformer: They offer sophisticated automatic generation tools to build top-quality SDKs and code snippets from API specific formats and transform them into other specification formations, such as RAML, API Blueprint, etc.

c) API Science: This tool is primarily used for evaluating the performance of both internal APIs and external APIs.

d) API Serverless Architecture: These products assist mobile app developers in designing, building, publishing and hosting APIs with the help of a cloud-based server infrastructure.

e) API-Platform: This is one of the open-sourcePHP framework that is apt for web API development.

f) Auth0: It is an identity management solution used to authenticate and authorize APIs.

g) ClearBlade: It is an API management provider for embracing the IoT technology into your process.

h) GitHub: This open-source git repository hosting service let the developers manage code files, pull requests, version control, and commenting that are distributed across the group. It also let them save their code in private repositories.

i) Postman: It is basically an API toolchain that empowers the developers to run, test, document, and evaluate the performance of their API.

Although the world is full of APIs and APIs, there is still a major gap in utilizing the perks of API. While some APIs make integration to the app a breeze, other turns it into a nightmare. To help you out in ensuring that you build a former one, here are some of the factors related to APIs for developers to consider:

Must-Have Features of an Efficient API

Modification timestamps/Search by criteria: An API should let the users search data based on different criteria, like a date. This is because it’s the changes (update, edit and delete) that we consider just after the first initial data synchronization.

b) Paging: Many times, it happens that we do not want to see the complete data changed, but just a glimpse of it. In such a scenario, the API should be capable of determining how much data to display in one go and at what frequency. It should also inform the end user about the no. of pages of data remaining.

c) Sorting: To ensure that the end user receives all the pages of data one-by-one, the API should empower the users to sort data as per the time of modification or some other condition.

d) JSON Support/ REST: Though not compulsory, it is good to consider your API to be RESTful (or providing JSON support(REST)) for an effective API development. The REST APIs are stateless, light-weighted and let you retry the upload mobile app process if it fails. This is quite tough in case of SOAP. Besides, JSON’s syntax resembles that of most of the programming languages, which make it easy for a mobile app developer to parse it into any other language.

e) Authorization via OAuth: It is again necessary that your API authorizes via OAuth since it is faster than other methods — you just need to click on a button and it’s done.

In short, the processing time should be minimum, response time good and security level high. It is of paramount importance to put efforts into the best practices for securing your application, after all, it deals with a heap of data.

Best Practices for Building the Right API

a) Use Throttling: App Throttling is a great practice to consider for redirecting overflow of traffic, backup APIs and safeguarding it from DoS (Denial of Service) attacks.

b) Consider your API gateway as Enforcer: While setting up throttling rules, application of API keys or OAuth, the API gateway must be considered as the enforcement point. It should be taken as a cop that lets only right users get access to the data. It should empower you to encrypt the message or edit confidential information, and thereby, analyze and manage how your API is being used.

c) Allow overriding HTTP method: Since some proxies only support GET and POST methods, you need to let your RESTful API override the HTTP method. For doing so, employ the custom HTTP Header X-HTTP-Method-Override.

d) Evaluate the APIs and infrastructure: In the current time, real-time analysis is possible to get, but what if API server is suspected to have memory leaks, draining CPU or other such issues? To consider such situations, you can’t keep a developer at duty. However, you can perform this easily via using numerous tools available in the market, like AWS cloudwatch.

e) Documentation: Last but not the least, it is profitable to create an extensive documentation for an API that let other mobile app developers easily understand the whole process and utilize the information for offering better user experience. In other words, a good API documentation in the process of effective API development will lessen the project implementation time, project cost and boost the API efficiency.


Imagine a waiter in a restaurant. You, the customer, are sitting at the table with a menu of choices to order from, and the kitchen is the provider who will fulfill your order.

You need a link to communicate your order to the kitchen and then to deliver your food back to your table. It can’t be the chef because she’s cooking in the kitchen. You need something to connect the customer who’s ordering food and the chef who prepares it. That’s where the waiter — or the API — enters the picture.

The waiter takes your order, delivers it to the kitchen, telling the kitchen what to do. It then delivers the response, in this case, the food, back to you. Moreover, if the API is designed correctly, hopefully, your order won’t crash!

Types of APIs

There are numerous types of APIs. For example, you may have heard of Java APIs, or interfaces within classes that let objects talk to each other in the Java programming language. Along with program-centric APIs, there are also Web APIs such as the Simple Object Access Protocol (SOAP), Remote Procedure Call (RPC), and perhaps the most popular — at least in name — Representational State Transfer (REST). There are 15,000 publicly available APIs, according to Programmable Web, and many thousands of more private APIs that companies use to expand their internal and external capabilities.

In the age of the smartphone, APIs mostly refer to the use of services running on a remote server for retrieving, storing, and processing data used by a mobile app or website. On paper this is not very different to SOA and the use of Web Services for distributed computing — however, in practice, there are some differences, which, in particular, stem from the increased popularity of REST:

The first key difference is the shift from services to resource thinking — this is sometimes referred to by REST community as Resource Oriented Architecture (Similar to how WWW was a web of interlinked documents, applications become a web of interlinked resources referring to each other through URLs. Applications tap into these resources and utilise new functionality through standard HTTP requests, no different to how web browsers download documents and images (that is, web resources) via hyperlinks. Whereas service oriented architectures have typically reflected a neat, pyramid like, decomposable hierarchy of services, in practice more than often running on the same middleware, resource oriented architectures are distributed and decentralised in nature, treating clients and servers as one and the same thing.

The second key difference is the use of plain old web standards such as HTTP(S) and JavaScript, deliberately avoiding the complexity of lengthy XML standards. Compared to the almost cathedral like layers of abstractions in contemporary Web Services standards, APIs take a rather minimalist approach using the protocols and languages of the web browser in pursuit of simplicity and reduced overhead. This is particularly important in the new market environment where the consumer of an API is more likely to be a smartphone device with limited bandwidth and battery capacity rather than a multi core desktop computer with endless processing power. That said, it is important to note that HTTP is not a necessity for APIs and REST. For instance, CoAP (RFC 7552 Constrained Application Protocol), which is a network protocol for small and low powered devices on the “Internet of Things”, is based on REST but does not use HTTP as the underlying transport protocol. Also, API platform vendors such as 3scale have developed API technologies that use WebSockets for interactive and fully persistent client-server API communications instead of the stateless HTTP.

The third key difference is deliberate statelessness. A stateless service means that each request to a service is treated as an isolated transaction with no knowledge of preceding requests, similar to how REST and the HTTP protocol work. Stateless is the opposite of stateful services where the service itself is required to automatically keep track of all its clients/consumers across intersections, resulting in much greater complexity. SOA enthusiasts often promoted stateless service design as a sound architectural principle, which architects should consider in their blueprints. However, SOA related Web Service standards such as WS-Transaction and WS-AtomicTransaction were still introduced to handle transactional state across services, both in terms of atomic transactions and so called long running processes. These standards were critical for SOA to fit into corporate enterprise environments governed by rich middleware platforms where transactions are key, but also signalled the departure from the elegance and simplicity originally touted by SOA. APIs, on the other hand, are deliberately stateless, partially due to the nature of the underlying protocol (HTTP) and partially due to its inherent simplicity. As a result, API designers need not worry about transactional management across API call, but it also leaves the API consumer, i.e. the app developer, with more work to manage error handling, rollback, and clean up on the client side. However, it is important to note that efforts have been made in the REST community to make REST stateful and transactional.

Outside of the pure technology reasons, APIs have gained traction due to the inherent focus on simple, practical deployment. This, in turn, made it easier for technology leaders to convince their bosses that it was worth the investment, simply because it was easy to deliver tangible results very quickly. The API deployment model, that is, where and how APIs are deployed, executed, and accessed by consumers, is often referred to as “microservices”3 — decomposing the business workflow into a set of extremely fine grained services, each of which only does one thing and does it well. A microservice is typically not bigger than 100–1000 lines of code, outside of which it is time to split it into two separate services. Here, the quick witted reader would ask: doesn’t that sound exactly like SOA? Conceptually yes, but microservices are different in that they are tied to a set of practical deployment principles, which SOA would never do in its effort to remain agnostic of any particular type of technology. Some of the key deployment principles are design outside-in, lightweight tooling, test automation, self-documentation, programmable deployment, and multi-channel.

Design outside-in means that APIs are designed to be deployed as a commercial offering to third party applications from day one. For instance, if you are writing a microservice API for a legacy mainframe-based warehouse management application, you would write the API so that it removes the complexity of the underlying mainframe technology and provides a simple, clean layer of objects for dealing with stock keeping units, inventory, shelf location, etc, exactly as you would do if you offered the API as a commercial product to a customer, i.e. as a managed warehouse solution. Not only does this encourage developers to strive for a clean, simple design — it also enables the strategic possibility of easily monetize new products and services, which were previously considered an internal support function. For instance, a consumer products retailer with a considerable warehouse and logistics capability, which were until now only used for serving its own stores, may suddenly decide to offer a managed warehouse and third party logistics solution to other businesses. Having simple, clean, and well documented APIs makes this strategy very achievable because the new customer base can quickly integrate existing systems to the mainframe backend. In addition, charging customers for the use of the new warehouse solution becomes trivial because accounts management and billing were embedded in the API design from day one. The use of API versioning means that new API functionality can be deployed gradually and gracefully without interfering with customers depending on existing APIs.

Lightweight tooling refers to the use of simple, lightweight development tools and runtime platform. Whereas SOA in practice was open promoted through the use of monolithic middleware platforms, typically based on Java or .NET, with an integrated development environment bolted on top, APIs have emerged out of much the need for “hacker friendly” command line utilities and text editors. Developers have favoured JSON, a JavaScript based language for describing data structures, over XML due to its focus on readability and limited need for data marshalling from objects to angle brackets on the API client side. Similarly, alternative languages and runtimes such as Node.js (server side JavaScript) have gained on the server side due to its minimalism, speed, and strong open source community backing, enabling developers to personalise their workflow and automate deployment. This has particularly resonated with technology start-ups where new platforms are often adopted to differentiate in the market whereas more traditional enterprise platforms tend to be avoided unless absolutely necessary.

Test automation is the use of scripts to automate unit, functional, and integration testing every time a change is made to the API code base. Whilst this is by no means a new phenomenon or specific to APIs, APIs enable fast testing because of the focus on rapid deployment. Whereas testing of complex middleware stacks can be challenging to automate due to the need for tearing down, reconfiguring, and bringing up multiple tiers at the same time, the lightweight architecture of microservices coupled with a container based infrastructure makes testing of APIs a lot easier and integration defects can often be discovered early.

Programmable infrastructure is the application of DevOps practices to deploy and operate API services and infrastructure. DevOps is a new concept, which applies agile development techniques to systems and network operations. For instance, instead of splitting development and operations into two separate teams or departments, DevOps stresses the need for operations people to work as part of a development team in order to increase collaboration. This is particularly useful for firms where APIs evolve rapidly and new versions are deployed weekly or even daily. Achieving and sustaining efficient DevOps requires significant automation of infrastructure services using tools such as Docker, Chef, and Ansible to deploy and manage releases to the cloud, automate configuration management, and reduce effort spent on manual administration tasks.

Self-scalability refers to the ability of microservices to automatically scale out on the fly without the need for waiting for IT to provision an entirely new virtual server, allocate storage, installing the operating system. etc. Since microservices are often associated with lightweight container technology (such as Docker), it is possible for an instance of a microservice to automatically spawn hundreds or thousands of new instances of itself on the fly during peak demands (and scale down as well). This is very different to the “classic” enterprise IT environment where enterprise services and dependent business applications are deployed in large hypervisors, which take a long time to prepare, provision, and spin up. The key difference lies in the ability of container technology to quickly deploy a new virtual machine image in milliseconds in combination with the deliberate stateless nature of microservices. By having no shared state between service instances, new service instances can be dynamically created, provisioned, and shut down, all transparently to the API consumer.

Multi-channel is the principle of designing all APIs for consumption by multiple devices and end users, providing a seamless experience regardless of the client. A commonly used technique for developing reusable APIs for multiple channels is using standards from mobile development such as JSON4 (Javascript Object Notation) for messages and OAuth5 for security, which ties well in with mobile native mobile/tablet application and web based applications. The lightweight overhead of these standards means that they fit well with devices where battery life and bandwidth are scarce.

All of the above principles are key to why APIs have caused wide disruption and adoption. That said, SOA is much less tied to its physical and practical manifestation. Therefore, we propose, it is probably more correct to view APIs as a practical application of and extension to SOA retrofitted to age of multi-channel retail and mobile devices.

How APIs deliver business value

Companies invest in APIs, not only for their technical elegance, but because they offer improved speed to market for new products and services. In the following we explore this in detail.

Firstly, speed to market stems from the fact that a small group of developed can very quickly build a prototype API and deploy it on a cloud service within days. Depending on the complexity of the underlying system or problem the API encapsulates, it is very easy to build a prototype application or web page, which invokes the API and mashes it up with data from other services. As long as the API contract (that is, the collection of input and output parameters and naming data types used to access the service), a development team can then gradually deploy changes to improve the service without impacting other parts of the overlying applications / service consumers. This model of decoupling application dependencies through simple interfaces fits very well with agile delivery teams that release new software early and often as they can iterate and deliver new features, provided that the API remains the same. Rapid prototyping of enterprise IT services suddenly becomes very real.

Secondly, speed to market stems from testability and automated quality assurance. Whilst SOA conceptually provided a great opportunity to automate testing through continuous integration practices, the influence of heavyweight ESB platforms made it very cumbersome to set up, test, and tear down an entire ESB environment without considerable effort and resources. The use of lightweight containers and low overhead run times for deploying and running APIs means that they are very easy and fast to deploy and script. Every time a change is made to source code, multiple integration tests can be run instantly with errors reported within minutes rather than at the end of a six months development cycle.

Finally, speed to market stems from simplicity, enabling changes to be implemented quickly. Where SOA through Web Services evolved into a web of abstractions supported by very complex, integrated tools, API developers often promote the use of text files and minimalist technologies to develop and deploy services. Changing a data type does not require new schemas to be generated, shared, or parsed. It is just a change in a text file. As a result, developers are more efficient resulting in lower costs to deliver, which, in turn, attracts new investments.

A key observation is that API efforts are often funded and driven outside of the traditional IT organisation. Similar to how mobile apps have grown as “skunkworks” projects emerging out of the marketing department, many companies build APIs as part of a strategy to launch a completely new product or spin-off. By being an integral part of a business model, APIs attract funding and capital that traditional business cases for SOA were struggling to find. A particular pattern I have observed is the strategy to take an in-house back-end function such as billing and payments and turn it into a revenue stream by encapsulating the function in a simple API and reselling it to other businesses on an as-a-service basis. For example, a large retailer had its own PCI-DSS6 compliant payments switch, which it used solely for its own stores. It successfully transformed this switch from a cost centre into a new revenue source by ‘wrapping’ the switch in a new public payments API offered to small retailers — at a lower rate compared to existing payment gateway providers, which were largely dominated by banks.

What it takes to deliver APIs: implications for delivery organisations

A key difference, which appears multiple times in this article, is the notion of how APIs are different to SOA and other enterprise IT approaches because of the way they are delivered. Agile and self-organising teams with development, infrastructure, and automation skills are often seen as the response, but there is much more to it. The transition to an API enabled enterprise requires large changes to the traditional way of planning, building, and running IT — we call it the two speed operating model for IT.

With APIs and other digital initiatives growing out of multi-channel marketing strategies and skunkworks projects, sometimes with only limited involvement of corporate IT, there is an increasing gap between what digital and IT delivery organisations require to operate. Digital focuses on quickly developing and delivering new digital offerings and APIs to the market whereas corporate IT focuses on keeping the lights on. Digital requires new technology capabilities, which can be too complex or costly to deliver on in houses or managed service infrastructure: on-demand cloud infrastructure, which allows for new virtual machines to be provisioned within seconds, software defined networks, and virtual load balancers with horizontal and vertical auto scaling in line with demand. Similarly digital delivery emphasises different skills with designers, developers, and DevOps engineers working in closely knit agile teams to deliver new services, whereas many traditional IT organisations operate on a plan/build/run basis relying on operational, service management, and sourcing experts to excel.

Whilst digital can often inject innovation, both capabilities are required for companies to be successful. Commoditised IT such as email, desktops, or IP telephony have no need for digital delivery or DevOps because their application and use are well tested — they are part and parcel of a robust corporate function. On the other hand, companies need to build digital capabilities to differentiate in the market and remain relevant to consumers. And the former is a requirement for the latter to experiment, fail fast, and succeed. This notion of a two speed IT operating model becomes the fabric on which APIs are developed because it relies on services from both worlds. Digital capabilities deliver the service front-end and deployment environment for APIs in order to quickly deliver and evolve a product. However, IT delivery capabilities are critical to keeping the lights on of the core business and run existing business and legacy business applications. Digital and IT delivery organisations complement each other in large organisations that need both new digital capabilities and stable core IT operations to succeed.

I have seen this modus operandi for IT organisations work particularly well for a very large global retailer, which was looking to build new multi-channel retail capabilities. The existing IT organisation had a reputation of being both slow and costly to run projects, resulting in business executives sourcing new capabilities externally. Whilst new digital initiatives were implemented faster and cheaper, it also meant that the retailer depended almost entirely on other companies to deliver and run its future core processes, which was a notable risk for a company with a digital agenda. We therefore explored idea of a new organisational blueprint in which technology was delivered through two different speeds within the company. The first speed was IT, reporting to the CIO, with its focus on existing business and legacy applications, which were key to keeping the lights on. The second speed was a new digital delivery group, reporting to the chief digital officer, which focused entirely on building new API enabled applications. Each group operated independently with their own technology stacks, delivery methodologies, and leadership, but with the shared purpose of delivering technology that enabled the retailer to differentiate in the marketplace.

APIs for the future — beyond mobile and channels

Moving forward, there are three key roles for APIs in the future beyond the typical areas of mobile and channel: moving to the core of the enterprise, nanoservices7, and connecting to the Internet of Things.

Firstly, moving to the core of the enterprise means challenging the stronghold of dominant enterprise applications and demonstrate that large monolithic platforms need APIs in order to adapt to changing business requirements new channels. Regardless of what enterprise software vendors may claim, what we consider ‘core platforms’ such as transactional banking platforms in financial services, policy/claims/billing platforms in insurance, merchandising platforms in retail, are all more or less monolithic in nature in that they depend on single, monolithic data stores, centralised processes to complete transactions, and complex interfaces to integrate. To truly embrace digital at the core of how enterprises work, core platforms will transform to be much more distributed and horizontally scalable in nature, similar to how channel platforms and B2B APIs work today. APIs are a means of making that happen by designing core banking, insurance, and retail platforms on the principles mentioned in this article: designing outside in, lightweight tooling, automation etc.

Second, we can expect to see the rise of “nanoservices”, very small microservices that are often deployed in unikernel based containers such as MirageOS8, providing improved horizontal scalability. Unikernel systems deploy applications on top of a shared address space machine image, which is tailored for the exact requirements of the application, leaving out unnecessary code or functionality. This means the resulting image (for deployment on a hypervisor) is very nimble, making it very fast to deploy and scale. For instance, instead of building a service in Java, which runs on the virtual machine inside a Docker container, which is a virtual machine running on top of a generic purpose Linux kernel with virtual memory management, which in turns runs on top of bare metal or in a virtual machine, unikernels does away with the proliferation of abstraction-upon-abstraction. The idea is that current technology has too many abstractions in place, creating too much overhead and complexity. Instead, services are deployed as a single application on top of a minimal kernel with only the exact code in place to make it run (e.g. a TCP/IP stack, threading, and Unicode support). Nano services become very fast to scale out, but the underlying technology is still considered experimental. Nano services are expected to become popular in the age of cyber crime due to the drastically reduced attack surface from stripping the userland and kernel to the bare minimum.

Thirdly, we can expect APIs having a big impact on the increased popularity of the Internet of Things (IoT). Whilst IoT startups are constantly building new innovations, there are little or no standards in place to ensure IoT devices and wearables can communicate. Enter APIs: building a standard API for IoT to interact and exchange data over a network is clearly the next use case for microservices. The real challenge then becomes building an API platform that can run on distributed, lower powered devices and securely route packages between different types of IoT gear, taking into account the mobile and fragile nature of IoT based networks (outside, on the go, mesh layout across a hospital), integrating equipment and technologies from many different IoT vendors.

With Great Functionality Comes Great Responsibility

APIs are pretty sweet, however if badly designed, they can also frustrate your developers to no end. Here are some criteria that I think is useful when designing APIs:

1. Make it clear what each endpoints do. While a Bank Teller tells you what the person does (sort of), titles like “Hyphenated-specialist” or “Professional Whistle Bending Expert” are not. Your endpoints should have basic names that is self-explanatory in purpose.

2. Errors should be clear and human-readable. Telling a customer that they don’t have enough balance in the bank is useful. Telling a customer that error #506340 has occurred is not. Although it might be tempting to save a few hundred bytes of data by returning an error code, in reality they just make everybody’s life harder.

3. Document everything. This is very important if you want your developers to not pull their hair out every time they encounter an error. Give them ample support with clear, concise documentation.

4. Be consistent. The last thing you need when the deadline approaches is frantic Googling just because this API endpoint acts slightly different from the rest. Make sure your naming conventions, error handling and other behaviour are consistent across all endpoints.

5. Keep your audience in mind. Think of how your developers will use your API, and make sure it is as easy and intuitive to use as possible.


1. What is REST API and SOAP API?

REST (Representational State Transfer) API is a software architectural style that describes a complete set of constraints to be employed for building Web services. Whereas, SOAP (Simple Object Access Protocol) is a protocol much complex by adding more standards than REST, such as security

2. How do I make a good RESTful API?

Making a good RESTful API is easier when you follow these practices:-

1. Use Throttling

2. Considering your API Gateway as Enforcer

3. Allowing overriding HTTP method

4. Making a proper documentation

5. Determine the APIs and infrastructure

3. What is API and types of API?

API (Application Programming Interface) is a collection of instructions, and requirements that let a software or mobile application utilize the features/services of other applications, platform or devices for exceptional services.

There are basically different types of API:-

§ Web service APIs

§ WebSocket APIs

§ Library-based APIs

§ Object remoting APIs

§ Class-based APIs

§ Hardware APIs, etc.

4. What is JSON API?

JSON (JavaScript Object Notation) is an encoding scheme created to eradicate the need for an ad-hoc code for each app to interact with servers in a particular manner.

My name is Jay Dwayne. A former baby, still a Fire Fighter and currently a Software Engineer. Thankyou for making it to the end of this Article.




Jay Dwayne is an interactive Software developer & Graphic designer striving to craft memorable experiences on the digital canvas. Currently based in Nairobi.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Using a local registry with Minikube

How to Contribute to the Kata Blog & Superuser Magazine?

Experienced Developers Are Allergic to These 5 Bad Optional Practices

Developer looking at Optional abuse and the cost of Java Optional abuse.

Andela Bootcamp day 3

Why R Programming Is The Most Trending Language?

Merging git repositories without lose commits history

Introducing Wild Credit V2 🎉

Improving your Magento 2 store’s page speed score

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Jay Dwayne

Jay Dwayne

Jay Dwayne is an interactive Software developer & Graphic designer striving to craft memorable experiences on the digital canvas. Currently based in Nairobi.

More from Medium

Secure Software Development Life Cycle (SSDLC) — A Practical Approach

Debugging OAuth Errors in Sigma

WebSockets, Server-Side Events, or HTTP?

My #Clojure Learning Journey — Part 1