Nowadays, almost every product has its own REST API; Google, Facebook, Twitter.
REST API provides a simple way for clients to interact with servers using the HTTP protocol. It has pretty much become the defacto standard protocol for web services, as it makes the horizontal growth much easier.
In this big data era, we have so many servers and systems to handle, that we need them to be easy to manage. REST API offers a truly flexible and scalable way of doing things as far as how we manage our clusters.
In this post, I will discuss the top advantages of using REST API to manage the grid and why you should consider making the shift yourself so as to make your work much more agile and scalable, thus saving you lots of time.
I’ll also explain how we created our very own XAP REST API and demonstrate some APIs using the playground provided by Swagger UI.
What is REST?
REST (REpresentational State Transfer) is a style of software architecture that uses the HTTP protocol for transferring data from client to server and vice versa. REST API defines a set of URIs (Uniform Resource Identifier) and specific actions that can be performed on each resource.
HTTP method names are used as actions like: GET (read), POST (create), PUT (update) and DELETE (delete). Resources that represent data can be received in several formats such as XML and JSON. Some HTTP methods (e.g. POST) allow sending data along with the request. It can be any type of data – such as string, number, XML, and JSON. The client and the server know how to parse it by reading the Content-Type Header of the request.
Using REST, the client and server are very loosely coupled, which makes it scalable. It is incredibly useful for building large and scalable systems. With REST, the server is free to change the exposed resources at will.
What can I get by using the REST API with XAP
In XAP 12.1 we’ve introduced a REST API for managing the grid components.
XAP provides the Admin API tool for monitoring and administering the cluster. It provides information and statistics on the currently running XAP services and components. It also enables registering listeners for various types of notifications ike service status changes, additions, removals, etc.
Here are 3 reasons why you should consider using XAP REST API for your grid management:
1. View cluster details in real-time and make client-side lighter
The Admin API is available for Java and .NET clients. The admin is a client-side component, which compiles data about the cluster constantly. In general, this is a good thing because you’re able to get data quickly. However, when we have a large cluster, it makes for a heavy client. If there is more than one client, each client has its own admin component. The data each admin receives is slightly varied due to the timing of each event sent. Events are usually received at different times, even by a few milliseconds, and some may be delayed. This creates a problem since each client sees a slightly varied picture of the cluster.
With REST, clients can send requests directly to the server, so there is only one source of truth which enables them to see the same view of the cluster. This solution helps make the client-side lighter. At the same time, if you write a REST client you can choose to cache the data locally. The benefits are clear – you, as a developer, have more control over how the data is stored and accessed from the client-side.
2. Use cross-platform programming languages for client
Another advantage to the REST API is that it works with any programming language since it uses the HTTP protocol. You can administer XAP with your favorite language. The beauty of REST is that you can access the server from your terminal (using curl in Linux) or even using the browser. It is easy to use.
3. Have one port to rule them all
The Admin API uses LRMI, our light version of RMI built on top of the NIO communication protocol. To support large amounts of concurrent access, each client opens a connection to a different port on the server. Read more here. If you are behind a firewall or using some cloud service for running XAP, you will need to open a wide range of ports on each machine in order to make it work.
With REST, actually HTTP, you don’t need to. HTTP supports multiple connections to the same port since each connection in HTTP protocol is identified by: source IP, source port, destination IP and destination port (TCP). If you have multiple connections from the same source, each connection will have a different source port that is unique for the connection.
How we built XAP REST API
In XAP 12.1 we’ve introduced a new component which hosts the admin on the server-side, providing a lightweight REST API on top of the grid. This way, the client can easily interact with the cluster with minimal overhead. This new component is called XAP manager. It consists of LUS, GSM, and ZooKeeper along with the REST API, which all run together in one process managed by the GSA.
We’ve chosen to use Swagger, a popular open-source API framework. We have written the API specification in YAML file in the OpenAPI format. This enabled us to use the Swagger CodeGen tool to generate the server stubs in Scalatra (web framework in Scala). XAP users can download the YAML file and use swagger tools to generate client libraries in various languages (Java, Javascript, .NET, python, etc.) to access the API.
We have also used Swagger UI, a tool that generates visual documentation and live playground for the REST API. This makes the interaction with the API’s resources super easy.
The REST API supports all the major functionality that exists in the Admin API. It allows performing operations on Deployments, Spaces, Containers and Hosts. We have a request notion for long running operations since we don’t want the client to wait for the result for a long period of time. The response of such requests includes a request ID in the body that can later be used for tracking its status. For the full list of the supported operations please refer to this documentation.
How to use XAP REST API
If you don’t already have XAP Premium/Enterprise 12.1, you’re welcome to visit our website and download it for a free 90-day trial. After downloading the zip file, go ahead and unzip it.
From the bin folder, run the following command:
./gs–agent.sh —manager–local
This will start the new XAP manager component mentioned above. By default, the REST API will be accessible via http://localhost:8090. Navigating to this URL will get you the Swagger UI page where you can try the API live on the running XAP instance.
Say we wanted to start one GSC on the current host. For that, we need to send a POST request to/containers URI. This URI accepts JSON that contains information about the desirable GSC; On which host it should be started, memory settings, zones, and custom VM arguments.
Let’s try it together. To start a GSC on my machine, I’ve used the below JSON as request body and clicked on Try it out!:
{ “hostname”: “yohana–pcu”, “memory”: “2g” }
We can see the result (response body) is 1 which is the request ID. Now we can send GET request to /requests/{id} URI to get information about the above request.
As you can see in the Response Body, our request was completed successfully. Now we have a new GSC in the system, once which we can get more information about via the new status URL.
Final thoughts
As you’ve seen, with REST API, and especially with our XAP solution, you can manage clusters easily in just a few simple steps. Our REST API for grid management helps facilitate the interaction between your application and the grid. It also provides a simple way for clients to interact with servers using the HTTP protocol.
Accessing the resources is possible by sending HTTP requests to the URIs the API defines. When your application needs to talk with multiple services, having REST API in these services ease the development as you will be able to use your preferred language to implement your application.
I hope this post helped give you an understanding of our REST API solution. If you’d like to know more, read on about or XAP Manager and XAP REST Management API.
Visit our website to learn more about what GigaSpaces has to offer.