dehaze

Quick Start

This guide helps you quickly get started with Remote Services. As mentioned earlier, remote services help you access your custom business logic via the unified API of Space Cloud.

In this guide, we are writing a service to carry out a complex arithmetic operation 😎. To be more precise, we are computing the addition of two numbers and returning the result 😛.

Note: We are using NodeJS and Express to write the remote service. However, you can choose any language or framework.

Prerequisites

Step 1: Writing a service

Let’s start by writing our remote service. We are going to use npm as our package manager.

First, create a folder that serves as our working directory.

Create NPM project:

npm init -y

Install Express:

npm install --save express

Write express server

Create a file index.js and copy paste the following code:

var express = require("express");
var app = express();

app.use(express.json());

app.post("/adder", function(req, res) {
  const num1 = req.body.num1;
  const num2 = req.body.num2;
  const result = { sum: num1 + num2 };
  res.status(200).send(JSON.stringify(result));
});

var server = app.listen(5000, function () {
    console.log("app running on port:", server.address().port);
});

As you can see, the code is pretty straight forward. We have just created an HTTP server using ExpressJS that is listening on port 3000.

This server listens for POST request on /adder endpoint. We are expecting to receive two numbers - num1 and num2 in the request body. All we are doing is returning the sum of these numbers. That’s all we need to perform our complex arithmetic operation 😛.

Step 2: Start the service

Simply run the following command to run the service:

node index.js

Great! We have our remote service up and running. Let’s start Space Cloud and use this remote service.

Step 3: Start Space Cloud

You can start Space Cloud in a docker container by simply runnning the following command:

docker run -d -p 4122:4122 --name space-cloud -e DEV=true spaceuptech/space-cloud:latest

Note: You can also start space-cloud without docker by following this guide.

Step 4: Configure Space Cloud

On running space-cloud, a config.yaml file gets generated in the directory from where you run space-cloud.

Space Cloud needs this config file to function. The config file is used to load information like the database to be used, its connection string, security rules, etc.

Space Cloud has it’s own Mission Control (admin UI) to configure all of this quickly.

Note: In distributed mode, Space Cloud stores the config in Consul instead of a file.

Open Mission Control

Head over to http://localhost:4122/mission-control to open Mission Control.

Note: Replace localhost with the address of your Space Cloud if you are not running it locally.

Create project

Click on Create a Project button to open the following screen:

Create a project screen

Give a name to your project. For this guide, we’ll use the name my-adder.

It doesn’t matter which database you choose here since we won’t be using it anyways.

Hit Next to create the project.

Step 5: Add remote service to Space Cloud

Head to the Remote Services section in Mission Control.

Click on the Add first remote service button to open the following form:

Add service screen

Put the service name as arithmetic and service URL as:

http://$HOST_ADDRESS:5000

Note: The $HOST_ADDRESS is the address of the host machine where the remote service is running.

Once you have added the remote service, you should be able to see it the remote services table:

Services table

Click on the View button in the Actions column to open the service page.

Click on the Add first remote endpoint button to open the following form:

Add endpoint screen

Put the endpoint name as adder and path as /adder.

Step 6: Query remote services

We have added our arithmetic service and the adder endpoint to Space Cloud. Time to query it using our unified GraphQL API.

Head to the Explorer section:

Explorer

Try running the following query in the GraphiQL explorer:

query {
  adder(
    num1: 10,
    num2: 20
  ) @arithmetic {
    sum
  }
}
{
  "data": {
    "adder": {
      "sum": 30
    }
  }
}

If you have noticed, you have to use the endpoint name inside query, and the service name as directive. The response is the object sent by the remote service.

Next steps

Great! You have learned how to write remote services! Next steps would be securing them.

Have a technical question?

Improve the docs!