Conceiving, planning and building useful APIs often requires serious time and effort. But if your API ends up being useful at all, managing your API throughout its life can be equally important. Fully hosted and managed by Restlet, APISpark is a Platform-as-a-Service (PaaS) solution dedicated to the creation, hosting, management and consumption of Web APIs. APISpark helps you host apps, manage existing APIs and document APIs. APISpark is free to use for an unlimited number of APIs with up to 10 concurrent clients.
This article will briefly take you through an overview of the features and benefits of APISpark:
- The APISpark “Introspector,” which automatically builds a Web API definition
- Building API Documentation, automatically generated
- APISpark API Management, focusing on authentication and firewall
I will walk through a text-and-screenshots tutorial with the exact steps for configuring and implementing APISpark’s key features.
For those wishing to jump ahead, Restlet provides great tutorials, user guides, FAQs and more to get you up and running quickly. APISpark Technical Resources are available here.
A companion video, Managing your API webinar, is also freely available.
The Starting Point
Let’s start our journey with APISpark’s Introspector. It is an open program, available on GitHub, that is easy to access and download. It analyzes annotations of some familiar Java frameworks for building APIs, the overall structure of the API and several other key components of the API. From here, the Introspector is able to infer a Web API definition and important metadata.
From the Web API definition, APISpark can create documentation for the API in a number of different formats, including Swagger and RAML.
Extending the API
Effective API management requires a set of tools that extend the API with only minimal development. The key component is an agent—basically, a reverse proxy that is positioned in between your devices and the API. You can download and configure the agent from the APISpark platform. For simplicity’s sake and for convenience, APISpark lets you run a stand-alone agent within APISpark itself.
The agent itself is open source, and you can always hack the agent for any specific use-case that you need. The following management features are available:
- Authentication: Who can invoke the API
- Authorization: Fine-grained access control
- Security: Firewall installation and configuration
- Analytics: HTTP response codes, response times, geolocation, and more
What do you learn in Programming 101? “Document your work.” As you become part of different teams or move from project to project, documentation only increases in importance. Somehow, however, it is always low on the to-do list.
With APISpark, it is very easy to make your Web API structure page public so that anyone can visualize the API structure. It is also easy to automatically export in RAML 0.8 and two versions of Swagger, 1.2 and 2.0.
A link is created and opens up the Swagger description of the API, showing who created it, a list of the paths, methods, types exchanged through methods, status codes, and more.
It is also possible to generate skeleton code, so that you can create an implementation of your API in various languages for different platforms (Java, Node.JS, etc.)