REST Server

REST Server exposes a set of interface that allows you to manage jobs.

Quick Start

1. Job config file

   Prepare a job config file as described in examples/README.md, for example, exampleJob.json.

2. Authentication

   HTTP POST your username and password to get an access token from:

   http://restserver/api/auth
   

   For example, with curl, you can execute below command line:

   curl -H "Content-Type: application/json" \
        -X POST http://restserver/api/auth \
        -d "username=YOUR_USERNAME" -d "password=YOUR_PASSWORD"

3. Submit the job

   HTTP PUT the config file as json with access token in header to:

   http://restserver/api/job/exampleJob
   

   For example, you can execute below command line:

   curl -H "Content-Type: application/json" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -X PUT http://restserver/api/job/exampleJob \
        -d @exampleJob.json

4. Monitor the job

   Check the list of jobs at:

   http://restserver/api/job
   

   Check your exampleJob status at:

   http://restserver/api/job/exampleJob
   

RestAPI

Root URI

Configure the rest server ip and port in service-deployment/clusterconfig.yaml.

API Details

1. PUT auth

   Update a user in the system, allowed by administrator only.

   Request

   PUT /api/auth
   Authorization: Bearer <ACCESS_TOKEN>
   

   Parameters

   {
     "username": "username in [_A-Za-z0-9]+ format",
     "password": "password at least 6 characters",
     "admin": true | false,
     "modify": true | false
   }
   

   Response if succeeded

   {
     "message": "update successfully"
   }
   

   Response if an error occured

   Status: 500
   
   {
     "error": "UpdateFailed",
     "message": "update failed"
   }
   

2. POST auth

   Authenticated and get an access token in the system.

   Request

   POST /api/auth
   

   Parameters

   {
     "username": "your username",
     "password": "your password",
     "expiration": "expiration time in seconds"
   }
   

   Response if succeeded

   {
     "token": "your access token",
     "user": "username"
   }
   

   Response if an error occured

   Status: 401
   
   {
     "error": "AuthenticationFailed",
     "message": "authentication failed"
   }
   

3. DELETE auth

   Remove a user in the system, allowed by administrator only.

   Request

   DELETE /api/auth
   Authorization: Bearer <ACCESS_TOKEN>
   

   Parameters

   {
     "username": "username to be removed"
   }
   

   Response if succeeded

   {
     "message": "remove successfully"
   }
   

   Response if an error occured

   Status: 500
   
   {
     "error": "RemoveFailed",
     "message": "remove failed"
   }
   

4. PUT job

   Submit or update a job in the system.

   Request

   PUT /api/job/:jobName
   Authorization: Bearer <ACCESS_TOKEN>
   

   Parameters

   job config json

   Response if succeeded

   {
     "message": "update job $jobName successfully"
   }
   

   Response if an error occured

   Status: 500
   
   {
     "error": "JobUpdateError",
     "message": "job updated error"
   }
   

5. GET job

   Get job status in the system.

   Request

   GET /api/job/:jobName
   

   Response if succeeded

   {
     name: "jobName",
     state: "jobState",
     createdTime: "createdTimestamp",
     completedTime: "completedTimestamp",
     appId: "applicationId",
     appProgress: "applicationProgress",
     appTrackingUrl: "applicationTrackingUrl",
     appLaunchedTime: "applicationLaunchedTimestamp",
     appCompletedTime: "applicationCompletedTimestamp",
     appExitCode: applicationExitCode,
     appExitDiagnostics: "applicationExitDiagnostics"
   }
   

   Response if an error occured

   Status: 500
   
   {
     "error": "JobNotFound",
     "message": "could not find job $jobName"
   }
   

6. DELETE job

   Remove job from the system.

   Request

   DELETE /api/job/:jobName
   Authorization: Bearer <ACCESS_TOKEN>
   

   Response if succeeded

   {
     "message": "deleted job $jobName successfully"
   }
   

   Response if an error occured

   Status: 500
   
   {
     "error": "JobNotFound",
     "message": "could not find job $jobName"
   }