Skip to content
This repository has been archived by the owner on Jul 24, 2019. It is now read-only.

Gold File Api

Jump to bottom
gojko edited this page Nov 24, 2014 · 18 revisions

MM Gold is a storage API used for server-side exports and sharing. Physically, it consists of two components:

  • Amazon S3 file storage
  • HTTP(S) API to obtain security tokens for the file storage

There are several JavaScript objects available in the MindMup source code that wrap the workflows and APIs presented here.

  • GoldApi class wraps the HTTP(S) api into a convenient JavaScript object
  • GoldLicenseManager is a utility that GoldApi uses to store and retrieve the account license
  • S3Api wraps the Amazon S3 response formats and polling into a utility class
  • The LayoutExport class wraps the file export workflow (polling etc)

Please note that although the HTTP interface is ready to be used as a public API, and will be backwards compatible in the future, the JavaScript objects might change in the future without notice. Use the JS objects just as an example, or write good tests for your code to catch any potential unexpected changes. All the objects are well tested with unit tests so check those out for example usage. For how to wire them up, see the main config file.

Executing Gold API calls

There are two HTTP endpoints you can use for your code

  • http://gold-staging.mindmup.com - our testing interface. it's resource limited and should only be used for testing your app against the APIs
  • https://gold.mindmup.com - the production end-point. Use this only via HTTPS, as the requests or responses will contain security sensitive information

Calls should be executed using POST, with HTTP form data arguments. For multi-versioning compatibility, all calls should contain an api_version parameter, containing the requested API version. The current API version is 2.

API calls will return a HTTP code 200 in case of success, and in cases where there is a response, a JSON response string.

API calls will return a non-200 response status in case of errors. Response body will contain a failure reason, which might be one of the following:

  • not-authenticated: the license is either missing or expired
  • invalid-args: the call arguments are incorrect (names or types)
  • server-error: unexpected server error - retry later

Obtaining a license string

For all file API calls, you'll need a Gold license. The license is effectively a secret key associated with an account, used to validate requests and for billing purposes. You can either provide all your users access through your server license, or let them use individual licenses.

The license string does not expire, and for automation purposes you should store it on a secure location on your server, or in client's browsers to avoid having to re-authenticate.

We don't use passwords so each login follows a typical reset password by e-mail scenario. You can request the license using a one-time password mechanism in two steps:

  1. Request a code to be sent by e-mail. Post to license/request_code. There response will be a HTTP 200 if the e-mail was sent. Any other response status should be treated as an error. Use the following POST FORM arguments:
  • api_version: the call API version you're accessing
  • identifier: either e-mail or account name associated with the license you're requesting
  • one_time_pw: a random string known only to you that will be used to validate the caller later. We use the MM.onetimePassword to generate this (from the GoldApi file), but you can use any random string up to 20 characters length.
  1. When you receive the e-mail, request the license using your one time password and the code sent in the e-mail: Post to license/request_license_using_code. There response will be a HTTP 200, with the license JSON text in the response body. Any other response status should be treated as an error. Use the following POST FORM arguments:
  • api_version: the call API version you're accessing
  • identifier: either e-mail or account name associated with the license you're requesting
  • one_time_pw: the one time password sent with the request_code call
  • code: the code string received in the e-mail

Ordering an export

To order exports from the service, you should:

  1. Call the HTTPS api to get a file upload token and result polling URLs
  2. Send the file to S3 using the upload token (note that some export types require a layout, some require the map file)
  3. Poll the result and error URLs periodically until one of them resolves with a file
  4. Present or send the file from the result URL to the users in case of success, or report an error
Clone this wiki locally