REST API's are gateways to Flint which provide an interface to run Flintbits from external systems. This is the reference document for the REST API and resources provided by Flint.

Structure of REST URL

To use REST API, external systems will make an HTTP request and parse the HTTP response.

Flint's REST API's use JSON or XML as a communication medium for standard HTTP Methods.

Structure of REST URI's is as follows:

http://hostname:port/v1/bit/run/flintbox_name:flintbit_name

// Example
http://localhost:3501/v1/bit/run/mybox:hello.rb
ParameterDescriptionrequired
hostnameHostname of the server on which Flint is installed ( default is localhost )true
portREST API Port Number ( default is 3501 )true
flintbox-nameName of the Flintbox ( Git repository ) recently created to store all the Flintbits and configured it ( mybox )true
flintbit-nameName of the Flintbit created and added to the Flintbox ( hello.rb )true

 

Flint REST API Authentication

HTTP Basic

Flint supports HTTP Basic authentication using username and password.

Set username and password in HTTP header

You can set x-flint-username and x-flint-password HTTP headers in request with valid username and password.

x-flint-username:admin
x-flint-passowrd:admin123

 

Set Flint Key in header

You can obtain valid flint key for your account from the UI console or ask Flint Admin to give it to you. You can set flint-keyheader with valid key.

flint-key:v0zAJsljulCDY2%2BMZ3XmFRJZNCIt3r7Kb4jYbSaQWQsLqU6nC1ol6YOuJEQ8VLf0 
 

Set Flint key in URL as parameter

If your REST call does not support adding headers (like github hook). You can also set flint-key as URL parameter for all the URL.

http://localhost:3501/v1/bit/run/mybox:hello.rb?flint-key=FLINT_KEY

 

Content-Type HTTP Header

Apart from the authentication headers flint also requires Content-Type header with valid input document type. The valid values are application/json and application/xml.

Content-Type:application/json
// OR
Content-Type:application/xml

If flint do not find Content-Type header it will construct JSON using request body and pass it to Flintbit.

 

Actions

Run Flintbit Asynchronously [Recommended]

Runs a flintbit in asynchronous way. Post body will have a valid JSON or XML document. Default timeout of 6000 ms will be used.

POST http://localhost:3501/v1/bit/run/mybox:hello.rb
 

See REST API response section for output parameters.

Run Flintbit Synchronously

Runs a flintbit in synchronous way. Post body will have a valid JSON or XML document. Default timeout of 6000 ms will be used.

POST http://localhost:3501/v1/bit/run/mybox:hello.rb/sync
 

See REST API response section for output parameters.

Run Flintbit Synchronously with Timeout

Runs a flintbit in synchronous way with user specified timeout. Post body will have a valid JSON or XML document.

Flint does not guarantee that the flintbit job will be complete in specified timeout. If the timeout value is reached it will return back the status of the job. You can always use Result API (discussed later in this document) to retrieve result at a latter point of time.

POST http://localhost:3501/v1/bit/run/mybox:hello.rb/sync/60000

 

See "REST API Response" section for output parameters.

Get Flintbit run Result

You can get run result of the job triggered asyncronusly or timed out before the run is complete.

GET http://localhost:3501/v1/bit/result/job-e381654d-065f-48f3-bbd4-f3420da18495

where, job-e381654d-065f-48f3-bbd4-f3420da18495 is the job id from the flintbit run request.

 

See "REST API Response" section for output parameters.

 

REST API Response

In case of synchronous requests an output object is set which is the actual output of flintbit. A meta object is always returned back along with the output of the flintbit. The meta object gives you additional information about the flintbit job you are running.

In case of asynchronous request only meta object is returned. You can query for the status of job using result api which is described above in this document.

Response parameters

ParameterDescription
job-idJob id is unique identifier of the request being submitted
exit-codeExit status code of the job run request. Zero value indicates success , non zero value indicates error
context Fullyqualified name of the flintbit that was run. Example - mybox:hello.rb
messageHuman readable job execution status messages. This can be a status or error message
statusStatus of the job run request. Possible status values are submittedrunningcompleteabortederror
timeoutTime out of the job run request
timestampTime at which the job was executed
content-typeContent type of the request being submitted. This can be application/xml or application/json

Example JSON

 

{
  "meta": {
    "job-id": "job-209bc504-887a-4614-b16d-480284364caa",
    "exit-code": 0,
    "context": "mybox:hello.rb",
    "message": "success",
    "timeout": 60000,
    "timestamp": 1435923867907,
    "status": "complete",
    "content-type": "application/json"
  },
  "output": {
    "message": "Welcome to Flint !!"
  }
}
 

Example XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<flint>
    <meta>
        <job-id>job-aab20c62-9460-439f-951d-7bcbe48a61fd</job-id>
        <exit-code>0</exit-code>
        <context>mybox:hello.rb</context>
        <content-type>application/xml</content-type>
        <message>success</message>
        <timeout>60000</timeout>
        <timestamp>1435927066310</timestamp>
        <status>complete</status>
    </meta>
    <output>
        <message>Welcome to Flint !!</message>
    </output>
</flint>

 

 

On this page: