DX, API Design & Documentation

Focus on the API Developer


A productive developer is a happy developer.  One of the most frequently discussed topics in the API economy is focusing on the needs of the Application developer – the consumer target for your APIs.  Make them happy! Make them productive! Meet their needs! This is the mantra. This in turn drives the success of your APIs and if all goes as planned, we drive business success.  Goal accomplished.

Today I want to focus on the other developer – the API developer – probably the least discussed role in the API space.  The API developer along with the API Product Manager (another important and frequently discussed role) are responsible for the creation of the APIs your business delivers.

What Does the API Developer Do?

The focus of the API developer role is the technical implementation of the API.  This includes creation of the API itself and potentially other assets invoked by the API as required. While thinking of this as one role, there are often many skills that are required.

First there is a need for skills as an API interface developer who deals with the Open API standards (OpenAPI, REST/JSON) and / or SOAP/XML. Perhaps this extends into GraphQL, Events, and other new technologies as the definition of an API expands.  And, there is a need for skills as a Microservice coder (included in the broad definition of API Developer) who introduce new or changed business logic in languages such as Node.JS, Java, Swift, or others. 

Since integration technologies greatly compliment the API Economy, API developers need to interact with integration experts to connect to internal and external resources including assets such as Web Services, databases, packaged applications (e.g. SAP), cloud applications (e.g. SalesForce), or other cloud APIs (e.g. Google Maps).  Assets accessed by an API may be in various locations inside the company and on one or more clouds. Integration architects and the API Developer need to work together to support this hybrid integration architecture.

Other technical responsibilities related to API creation and lifecycle management are also included in this larger “API Developer” role category. This may include defining API standards, naming conventions, API architecture, Lifecycle governance, etc.

Supporting the API Developer

Perhaps we should not be taking the API developer for granted.  This is a critical role in our path to API success. So, how do we make the API developer a productive developer and therefore a happy developer?

Given the wide array of responsibilities, the API developer requires more than one tool or framework to accomplish their tasks. Let us call these an API Development Environment (ADE) or API toolkit. Most of the ADEs available in the market are browser-based and do not provide the native experience developers are used to with traditional IDEs. Typical characteristics of an IDE are applicable to an API Development Environments too. It should be a single click install, no startup time, fast and easy to use. And it should provide the ability to work in isolation on one’s laptop for rapid iterative development even if disconnected from the network with the freedom to work untethered (although working on aircraft is difficult, it has been often most productive).

The ADE should be comprehensive to address all aspects of API development.

It should support the API developer’s ability to create microservices and design APIs based on OpenAPI standards. It should allow them to define the behavior and test their APIs iteratively without long deployment delays. While an ADE should offer a friendly graphical user interface (GUI) reducing any learning curve for API development.  And, it should also provide a Command Line Interface (CLI) for experienced developers.

API developers must be able to add an API definition either by composing the API definition (top-down), and its operations, from scratch, or by importing an OpenAPI definition (bottom-up). Thus, the ADE needs to be extremely flexible.

The ADE should have a graphical interface for the OpenAPI definition (like the swagger editor) while allowing the developers to directly edit or update the OpenAPI definition in the source (Yaml or JSON). It should allow the developer with a drag and drop user experience to decorate the API with the right set of policies for enforcement (often done on an API management solution). It should allow the developer to iteratively dev-test and debug their APIs in a rapid fashion without any external dependencies. Finally, when ready with the API, the developer should be able to easily push the assets into an API Management platform to continue the lifecycle management and to source code management.  All of this power on one’s laptop!

As you can see the focus should be on removing any unnecessary governance and overhead in the early stages of development thus improving the developer productivity.

Looking forward, the tool needs to be actively enhanced and maintained to handle newer capabilities as they become needed.  Look for tools that have plans to support GraphQL and continue to be enhanced as the API world moves forward. This enables the developer to continue to use their familiar development environment as technologies evolve.

Using a local ADE reduces errors and improves the API developer productivity => happy API Developer => better quality APIs, faster.

If you have questions, please let me know.  Connect with me through comments here or via twitter @Arglick to continue the discussion.  

Alan Glickenhouse
Alan Glickenhouse is the IBM Digital Transformation and API Business Strategist.  Alan assists clients with their business and IT strategy for Digital Transformation and the API Economy.  Starting with an understanding of the business direction, current IT strategy, and existing environment (both business and technical), Alan helps businesses successfully adopt a Digital Transformation and API strategy that fits their environment. He meets clients in all industries, all geographies, and of all sizes and brings knowledge of best practices shared with and by these businesses.  Alan is the author of over 150 papers, articles and videos on these topics.  

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture