In this post we will explore utilising Mobile Cloud Service (MCS), which provides RAML based tooling, in order to define an API, and create mock services for that API which we can run anywhere. While Mobile Cloud Service provides a wide array of incredibly useful tools for rolling out APIs, and simplifying a number of common mobile development tasks; in this post I am going to focus exclusively on the API design tooling which far outstrips pretty much every other API design tool I have played with.
Defining the APIs using Mobile Cloud Service
To begin with, we will use Mobile Cloud Service to define our API. From the Mobile Cloud Service launch page, drill down through Applications to APIs, and create a new API. In this scenario, we will build out an API for marketing events, which lists upcoming events, allows users to register, displays biographies of presenters etc.
This generates a simple RAML document, which can be seen by clicking the ‘Enter RAML Source Editor Mode’ button in the upper right of the screen.
As we can see, this is pretty simple:
#%RAML 0.8 title: Marketing Events API version: 1.0 baseUri: /mobile/custom/promotional_events protocols: [HTTPS]
If we go back to the General page, and set the base media type to ‘application/json’, we can see the RAML updated appropriately:
#%RAML 0.8 title: Marketing Events API version: 1.0 baseUri: /mobile/custom/promotional_events protocols: [HTTPS] mediaType: "application/json"
From here we can use the MCS tooling to add endpoints, responses, etc. This builds out the rest of the RAML file in the background. This post won’t go into too much detail about using the Mobile Cloud Service API tooling; I find that it is pretty self-explanatory, and well structured. If you are looking for more information, I cannot recommend the MCS YouTube channel highly enough.
I fleshed out the API with a number of endpoints for the marketing event scenario, to enable listing of events, creation of events, attendees to register/deregister, etc.
Endpoints themselves were described, with parameters and payloads defined. The end result of this is a RAML file (available below), which describes the API. Only the top level /events endpoint has been filled out, other top level endpoints have been added simply to make the subsequent documentation look better.
Files at the point:
Generating Mock Endpoints
Another advantage of using Mobile Cloud service to define our APIs is it allows us to download a Node.js scaffold for the implementation of the API. This scaffold can be used to build out a full API implementation leveraging Mobile Cloud Service connectors, object stores, data bases, etc. For our purposes, we are going to simply use this generated file in order to spin up some mock service endpoints.
Begin by pulling down the scaffold.zip file, and extract it to obtain the javascript file which defines the endpoints. As of MCS version 16.3 or so, the generated scaffold includes all of the sample responses and status codes we defined in the RAML document; perfect for mock services!
Mobile Cloud Service extends the Express framework with a number of helpful features for implementing APIs, but for the purpose of mock services, the initial scaffold only needs Express. As such, we will wrap the generated scaffold file with an Express application in order to leverage it for development.
In order to do this, we will leverage npm to build a new Node.js application, incorporate Express, and write a tiny bit of javascript code to incorporate the javascript scaffold obtained from MCS.
Begin by creating a new directory with an appropriate name for the project, i.e. ‘marketing-events-mocks’, then run ‘npm init -y’ in that folder which sets up a package.json file, with default settings. As the plan isn’t to make this package generally available, the defaults will be fine. From there, we will add the express framework, using ‘npm install express’
From this point, we need to copy the javascript scaffold into the root of our express application, and set it up as available endpoints through a handful of lines of code. I created an app.js (though the actual name doesn’t matter) in the root of the project, with the following content (where ‘promotional_events’ is the name of the scaffold file obtained from MCS).
var express = require('express');
var app = express();
app.use(function(req, res, next) {
res.header("Access-Control-Allow-Origin", "*");
res.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
next();
});
require('./promotional_events')(app);
var port = 3000;
app.listen(port, function () {
console.log('Mock services listening on port ' +port +'!');
});
The only real piece of code to note is the setting of the ‘Access-Control’ headers to allow for CORS access. For many scenarios, they are not required, but I tend to find that inevitably you will be performing some testing and it will come back to bite you. I find it easier to set them by default, just to save headache down the line.
Running this with ‘node app‘ will start the server running locally on port 3000, and you can test it by hitting an endpoint such as ‘http://localhost:3000/mobile/custom/promotional_events/events’
Aside: As of the time of writing, MCS version 16.4.1 is using an older version of express, and the generated scaffold reports warnings when an endpoint is invoked with the default version of express which is downloaded with ‘npm install express’ These warnings can be safely ignored.
If they start to annoy you too much, a find and replace of:
res.send(statusCode, result)
with
res.status(statusCode).send(result)
in the scaffold file will resolve them.
Files at this point:
- RAML Descriptor
- Generated Mock Services file from MCS
- app.js to run the Mock Services
From here, feel free to spin up that Node.js application on an addressable server for testing. I find it is helpful to make this service available to your UI developers, even while (and after) the APIs are being implemented, as it is handy to have a mock endpoint under their control, without the need for any of the MCS authentication wrangle.
RedThunder.Blog 