MathML Cloud, as developed by Benetech, consists of two code libraries:
- Entering equations in various formats, and requesting output in different formats
- Reviewing and commenting on the results
- User administration
The Benetech-hosted runtime of MathML Cloud is currently hosted on Microsoft Azure in a Linux VM, with MongoDB hosted by the MongoLab service. There is a staging and live environment which are virtually identical.
While the separation of concerns between the app and the API allow them to be hosted separately, in the Azure environment we have made some compromises.
MathML Cloud exposes the resources that it handles through a RESTful API: equations, uploads, comments, and users, which clients can retrieve, save and update. See the API Definition for the parameters and responses that are available.
As an example, a developer at a publisher house creating software that interfaces with the MathML Cloud API might create a POST request to mathmlcloud.org/equation to convert AsciiMath to MathML, or create a GET request to view the converted equation and all of its components. The code to do this would be running in their authoring software behind the scenes.
We are not currently using Azure's API Management service, After setting it up and testing it, there were enough cases of errors that we weren't able to diagnose ourselves, or with Azure API Support, that we decided to not use it. We are looking for other API management services to help us manage endpoint traffic and client access.
From the Azure Portal API Management help window:
“Publish APIs to developers, partners and employees securely and at scale.
- Scale to millions of API calls
- Throttle, rate limit and quota your APIs
- Bring modern formats like JSON and REST to existing APIs
- Mobile enable enterprise APIs
- Maximize developer success with interactive console
- Get deep insights with rich analytics
For an overview of API Management, see http://azure.microsoft.com/en-us/services/api-management/.”
When we make use of Azure’s API Management, a developer would sign up for a developer key and then send all requests to api.mathmlcloud.org instead of mathmlcloud.org. The API Management Service would receive the request, do what it does, and then send the request through to mathmlcloud.org.
One of the key features that API management gives you is control over endpoint traffic and client access. If a malicious hacker wanted to, they could write a script that sends thousands of requests per second to mathmlcloud.org/equation and take down the site. If we were using Azure’s API Management system, the only way they would be allowed access to the API would be to sign up for a developer key and then present that key with each API call.
- We now know who they are
- We are be able to throttle their requests to a reasonable amount
- We are able to cancel their account if we suspect abuse
The MathML Cloud web application is a client of the API. It serves a UI to a user who wants to use a browser to send requests to the API. The app runs entirely in the browser, and has no knowledge of the API other than the URL to use to communicate.
The app is meant to be merely one example of a way to work with the API, and handles low-volume equation conversion. It serves as an introduction to the concepts and potential of the MathML Cloud API.
- Azure Management Console: https://manage.windowsazure.com/benetechmail.microsoftonline.com#Workspaces/All/dashboard
- RESTful API definition: http://www.restapitutorial.com/lessons/whatisrest.html
- API definition: http://www.theguardian.com/media/pda/2007/dec/14/thenutshellabeginnersguide