Web service hosting

Formulative provides easy deployment of highly available auto-scalable web services generated from your mathematical model hosted on the Amazon Web Services (AWS) platform.

Calculations can be invoked through our HTTP API. Authentication is done via Client Credentials Grant.

Web service containers

After a build was generated for the Web service target the result may be installed and uninstalled at any time. As an installation target a web service container must be selected. Web service containers specify how your installed builds will scale and the amount of resources to be allocated.

Client applications

Client applications provide client credentials to access our hosted web services and also act as a means of access to downloadable build artifacts by sharing them with Integrators.

The calculations a client application may invoke via our HTTP API depends on the build configurations they may access. Authorizing access to a build configuration allows the client application to invoke all the calculations provided by the installed builds of that configuration.

The downloadable builds accessible to an Integrator is also determined by the authorized build configurations.

Note

Client application access may be limited in an organization by organizational roles. Learn more about organizations

Invoke web services

The credentials provided by client applications are used to authenticate with our API via Client Credentials Grant.

The application must meet the requirements of a confidential client:

Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.

1. Ask for a token

Before calling your calculations you must acquire an access token. Every calculation request will need to include this as Bearer access token to authenticate.

Access token request

The token endpoint https://app.formulator.io/api/oauth/token expects the Client Credentials Grant / Access Token Request format specified in the The OAuth 2.0 Authorization Framework RFC.

POST /api/oauth/token HTTP/1.1
host: app.formulator.io
authorization: Basic MzMzNDcxMzFlNjg4ODAxOTA2ODE3OGU2ZmYxZGMx...
content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

The following request format is also supported for convenience:

POST /api/oauth/token HTTP/1.1
host: app.formulator.io
content-type: application/json; charset=utf-8

{
  "grant_type": "client_credentials",
  "client_id": "33347131e6888019068178e6ff1dc171",
  "client_secret": "e5422115fed177b94873647f790af6ee...",
}

Where:

  • grant_type must be "client_credentials".
  • client_id is the id of your client application.
  • client_secret is the secret of your client application.

cURL example:

curl --request POST \
  --url 'https://app.formulator.io/api/oauth/token' \
  --header 'content-type: application/json; charset=utf-8' \
  --include \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "33347131e6888019068178e6ff1dc171",
    "client_secret": "e5422115fed177b94873647f790af6ee..."
  }'

Access token response

The response complies with the Client Credentials Grant / Access Token Response format specified in the OAuth 2.0 RFC.

Example success response:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
cache-control: no-store
pragma: no-cache

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Where:

  • access_token: will be a JSON Web Token (RFC 7519)
  • token_type will be "Bearer"
  • expires_in contains the number of seconds the token is valid for

For errors check the RFC.

After the token is expired you must request another one.

2. Invoke your calculations

Calcultion request

To execute your calculations perform a POST HTTP request to the https://app.formulator.io/api/calculate endpoint with the Authorization header containing the acquired access token. The following format is expected:

POST /api/calculate HTTP/1.1
host: app.formulator.io
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
content-type: application/json; charset=utf-8

{
  "project": "mortgage",
  "buildConfig": "default",
  "version": "1.*",
  "calculation": "mortgagePmt.pmt",
  "params": {
    "term": 30,
    "interestYearly": 6.5,
    "principal": 200000
  }
}

Where the parameters are the following:

  • project: The id of the project that contains the requested calculation.
  • buildConfig: The id of the build configuration to use.
  • version: The version or version range to determine which published build to use. Examples:
    • 1.2.1 will use the exact version
    • draft will use the draft build, this should be used only during development
    • 1.2.* or 1.2 will use the latest version starting with 1.2.
    • 1.* or 1 will use the latest version starting with 1.
    • * will use the latest published version, this is not recommended to be used in production because major changes will probably break your client (versioning rules)
  • calculation: The id of the calculation group with the id of the calculation separated by a dot: "calculationGroupId.calculationId"
  • params: An object with the desired values given for all the required input variables of the calculation. Input variables must be referenced with their id-s in your calculations.

Example:

curl --request POST \
  --url 'https://app.formulator.io/api/calculate' \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer eyJz93a...k4laUWw' \
  --include \
  --data '{
    "project": "mortgage",
    "buildConfig": "default",
    "version": "1.*",
    "calculation": "mortgagePmt.pmt",
    "params": {
      "term": 30,
      "interestYearly": 6.5,
      "principal": 200000
    }
  }'

Calculation response

Example success response:

HTTP/1.1 200 OK
content-Type: application/json; charset=utf-8
x-version: 1.1
x-calculation-time: 10
cache-control: no-cache

{
  "monthlyPayment":1264.14
}

Where:

  • the x-version header includes the resolved version
  • the x-calculation-time header includes the number of milliseconds the calculation took on our servers

Error response format:

When the calculation referenced does not exist the server will respond with a status code of 404 with the following body:

{
  "code": "CALCULATION_NOT_FOUND"
}

When there is a problem with the request body format the the server will respond with a status code of 400 with the following body:

{
  "code": "BAD_REQUEST",
  "message": "..."
}

Runtime calculation errors and input validation errors will be returned with a status code of 500 with the following body as an example:

{
  "code": "CALCULATION_FAILED",
  "message": "..."
}

Unexpected errors will be returned with a status code of 500 with the following body:

{
  "code": "INTERNAL_SERVER_ERROR"
}