Use Case: Rapid REST API Development

MAE has created all the mechanics of receiving, decoding, encoding, and responding to REST API calls as well as a prototype daemon as a code starting point. Your developers focus on the core functionality of your REST API services. This makes for rapid REST API development.

Problem

Your organization is being asked for REST API access to your software, but you don't have REST API development experience on your team.

Or perhaps you have REST API development experience, but the development process is complicated or subject to frequest software revisions which requires more time for your development team than is available.

Either way, you need a solution to allow your development team to create REST APIs quickly, in a straightforward manner, and with minimum software maintainence.

Solution

MAE comes with all the mechanics to handle a REST API call and deliver it to your software as a request. Create a MAE application to handle the request(s). Your software handles the request to produce a response and sends that response back. Your software doesn't need to worry about web server configuration, data type decoding, data type encoding, or user authentication. Your software focuses on the core functionality of the REST API.

Today, MAE supports the HTTP operations of GET, POST, PUT, DELETE, and PATCH. Future releases will support more operations.

You can version your API calls. MAE supports multiple REST API applications; each application is given its own channel, which appears in the URL, such https://maeserver/channel/request. MAE handles decoding and encoding to JSON and XML for your app.

Ask HanoverSoft

Does this solution look like a fit for your organization? Reach out to HanoverSoft at +1 (919) 270-6712 or info@hanoversoft.net to discuss.

Implementation Guidance

Your REST API URL will follow one of this general form:

https://maeserver/channel/[version/]request[/submode(s)][?parameters]
payload

where the parts of the URL are:

Part	Description
maeserver	This is the hostname or IP address of the MAE server that you setup for your REST API server.
channel	Related requests are grouped under a channel name. Often the channel name is also the app name that handles the REST API call. When you app start, it registers this channel with usergw ([see a Channel with UserGW]).
version	This optional parameter can be introduced if/when you later need to revise your REST API. This often takes the text form v1, v2, etc.
request	Often a REST API is designed to query/manage/manipulate related objects. The request name is many times the object type, e.g. person, vendor, etc.
submode(s)	A calling application can optionally specify additional elements of the URL path. These will be passed to your application for interpretation.
parameters	The GET method as well as the others supports parameters in the typical URL form of key=value with multiple key/value pairs separated by ampersand (&). This the parameters are part of the URL, you'll need to URL-encode them (convert symbols like + and & to hex, spaces to +, etc.)
payload	The POST and other non-GET methods may post a data payload. See the HTTP protocol for details.

Here is a sequence diagram that shows the intra-MAE mechanics of a REST API call. Most of the work in the MAE actor is UserGW.

Registering a Channel with UserGW

To register your MAE app to receive requests when REST API calls come to UserGW, make sure you add a call to DisplayAPI::registerApp() in your MAE::init() code. Here's an example:

DisplayAPI::registerApp(/*appmode*/ "rest" /* https://sitename/rest/... */,

/*apptype*/ "Direct",

/*action*/ "rest-call",

/*contentInputType*/ "json",

/*contentOutputType*/ "json",

/*operations*/ StringList("GET,POST,PATCH,DELETE"),

/* msgchannel */ "" /* our primary channel */,

/* privatePages */ false);

Once registered, your app will receive a request for rest-call, which you configure in your .mreg file, like this:

#msg "rest-call" cmdRestCall(const string & appmode, const StringList & submodes, const string & method, const string & conntype, const string & authuser, const string & authtoken, const XMLData & params, const string & content)

/** Handle a page request.

* @param device - end-user's device

* @param appmode - Name of appmode, likely the app's name. All URL's for //site/appmode/ will trigger a message using action below

* @param submodes - - parts (in sequence) of the URL request (between the slashes)

* @param method - type of user request, e.g. GET, POST, PATCH, DELETE

* @param conntype - type of behavior to remote client: Ux (asynchronous user experience in browser), Direct (synchronous query gets synchronous response), Pipe (streamed data from remote connection is fed to app by line or binary block)

* @param auth - the provided authentication token by the caller

* @param params - key/value pairs of values provided in the request (whether in URL or POST form-data)

* @param content - any content provided with request

#param appmode=@device.getAppMode()

#param submodes=submodes

#param method=method

#param conntype=conntype

#param authuser=authuser

#param authtoken=authtoken

#param params=@param.getChild("params")

#param content=content

which in turns calls the method cmdRestCall() with all the data from the REST call. Note that the payload data is inside params.

Replying to REST API Call

As can be see in the REST API sequence diagram above, your app makes two or more calls to UserGW to reply:

DisplayAPI::startraw() - Specify the return code (success, error, etc.) and encoding to use for the response (e.g. JSON)
DisplayAPI::writeraw() - Send the response content; this may be called multiple times
DisplayAPI::closeraw() - Signal to UserGW that the response content is complete

Sample MAE REST API App

MAE comes with a work sample REST API app called MaeRest, which your development team can use as a starting point.