How To Easily Develop Web APIs with APISpark

Fully hosted and managed by Restlet, APISpark is the first Platform-as-a-Service (PaaS) dedicated to the creation, hosting, management, and consumption of Web APIs. APISpark helps you host apps, manage existing APIs, and document APIs, all with a minimum of extra programming. APISpark is free-to-use for an unlimited number of APIs with up to 10 concurrent clients.

In this article, we will show how to develop a contact management Web API with APISpark, exposing structured data. We will see how to create a Web API from a data model allowing the tool to create the corresponding resources and representations. We will also show how the data source is easily synchronized with the elements exposed by the Web API and how their deployment can be done in just one click with the Deploy button. You no longer have to worry about hosting issues, availability and scalability. The platform manages for you.

We also cover APISpark’s integration with Swagger UI to graphically deploy the Web API. This makes it easy to test APIs and actually see the data exchanged. However, you do not have to use languages like Swagger and RAML to take advantage of APISpark. You can leverage wizards or create Web APIs from scratch.

We will also describe how to import and document a Web API whose structure is available in the Swagger format. This allows access to generated content such as programmatic clients, application servers and skeletons of documentation.

First, we will discuss some of the main concepts around Web APIs and REST.

Main Concepts of Web APIs and REST

A Web API is a set of resources available on the web via Uniform Resource Identifiers (URIs) that expose operations in the form of standard HTTP methods and representations defining the structure of the messages exchanged. A Web API allows work with data regardless of format, such as JSON, XML or YAML, through HTTP content negotiation. Web APIs are closely related to Representational State Transfer (REST) concepts, a popular Web architecture style consisting of guidelines and best practices for creating scalable web services..

APISpark is a cloud platform, or a Platform-as-a-Service (PaaS), for creating, hosting and easily managing Web APIs. It provides an online integrated development environment (Web IDE) and a hosting service. It allows a set of Web APIs based on the concepts of REST. Its GUI guides the developer to expose resources and treatments behind a URI.

The power of APISpark lies in the fact that no coding is necessary since the interactions between Web APIs and the backend can be configured visually.

Web APIs are based on the concepts of REST, an architectural style targeting distributed systems on the web. One of the key concepts is the lack of state at the server. Indeed, each request from a client to a server must contain all the information necessary to allow the server to understand the request.

Although this architecture does not depend directly from the HTTP protocol, it is particularly suitable for implementation of these concepts.

Before detailing how to graphically define Web APIs using APISpark, we will quickly review the main concepts of REST.

The central concept of REST is the resource. Resources handle a particular type of data and need to be managed in a special way. It is not possible to define multiple resources to manage the same data type: for example, one for the list of items and another for unitary member.

A resource is available on the Internet from a URL, and it is possible to interact with it with a set of predefined methods to recover the associated status, update and possibly perform other treatments. With HTTP, we can take advantage of the different methods (also called verbs) that the protocol provided.

The format of the data exchanged corresponds to the representation. This is a logical structure of data not linked to any particular format such as JSON or XML YAML. This structure can have attributes with nesting levels. The content of a representation with a particular format is called variant.

Figure 1 illustrates the concepts described above and their relationships.
Concepts of Web APIs and REST
HTTP provides a set of methods with precise semantics that must be followed to comply with the REST architecture. Take the example of the two resources to manage a contact: one at the contact list (with URL / contacts /) and the other at a particular contact (with the URL / contacts / { contactid}). We describe below the conventional use of HTTP in this context:
GET - Used to retrieve the status of a resource such as a contact list if used in the list resource type or a particular contact on unit resource.
POST - Adds a touch if used in the list resource type.
PUT - Allows you to completely replace the contact data if used on a single resource.
PATCH - Allows a partial update of the state of the resource. It is typically used for mass updates on the list resource type and to change only certain fields on the unit resource.
DELETE - Eliminates a particular contact.
Figure 2 describes the different methods of usable resources to manage data.
different methods of usable resources to manage data
Now that we have seen the principles of web APIs, we can discuss how APISpark allows extremely simple implementation.

Thierry Templier is the Lead Architect at Restlet. He has defined the architecture and is a core developer of APISpark, a platform to build and host Web APIs easily.