Zoe REST API¶
Zoe can be used from the command line or the web interface. For more complex tasks also an API is provided, so that Zoe functionality can be accesses programmatically.
The API is provided by the zoe-api processes, on the same port of the web interface (5001 by default). Every URL of the API contains, after the hostname and port, the path /api/<api version>/
. The current API version is 0.7.
In case the request causes an error, an appropriate HTTP status code is returned. The reply will also contain a JSON document in this format:
{
"message": "missing or wrong authentication information"
}
With an error message detailing the kind of error that happened.
Some endpoints require credentials for authentication. For now the API uses straightforward HTTP Basic authentication. In case credentials are missing or wrong a 401 status code will be returned.
Info endpoint¶
This endpoint does not need authentication. It returns general, static, information about the Zoe software. It is meant for checking that the client is able to talk correctly to the API server:
curl http://bf5:8080/api/<api_version>/info
Will return a JSON document, like this:
{
"version" : "2017.06",
"deployment_name" : "prod",
"application_format_version" : 3,
"api_version" : "0.7"
}
Where:
version
is the Zoe versiondeployment_name
is the name configured for this deployment (multiple Zoe deployment can share the same cluster)application_format_version
is the version of ZApp format this Zoe is able to understandapi_version
is the API version supported by this Zoe and should match the one used in the request URL
ZApp validation endpoint¶
This endpoint does not need authentication. Use this endpoint to validate ZApp descriptions against the deployed Zoe version.
Usage:
curl -X POST --data-urlencode @filename http://bf5:8080/api/<api_version>/zapp_validate
Needs a JSON document passed as the request body:
{
"application": <zapp json>,
}
Where:
application
is the full ZApp JSON document, the application description
Will return a 200 HTTP status in case the JSON document passes validation, 400 otherwise.
Execution endpoint¶
All the endpoints listed in this section require authentication.
Execution details¶
Request (GET):
curl -u 'username:password' http://bf5:8080/api/<api_version>/execution/<execution_id>
Where:
execution_id
is the ID of the execution we want to inspect
Will return a JSON document like this:
{
"status" : "running",
"description" : {
"version" : 2,
"will_end" : false,
[...]
},
"error_message" : null,
"time_start" : 1473337160.16264,
"id" : 25158,
"user_id" : "venzano",
"time_end" : null,
"name" : "boinc-loader",
"services" : [
26774
],
"time_submit" : 1473337122.99315
}
Where:
status
is the execution status. It can be on of “submitted”, “scheduled”, “starting”, “error”, “running”, “cleaning up”, “terminated”description
is the full ZApp description as submitted by the usererror_message
contains the error message in casestatus
is equal to errortime_submit
is the time the execution was submitted to Zoetime_start
is the time the execution started, after it was queued in the schedulertime_end
is the time the execution finished or was terminated by the userid
is the ID of the executionuser_id
is the identifier of the user who submitted the ZApp for executionname
is the name of the executionservices
is a list of service IDs that can be used to inspect single services
Terminate execution¶
This endpoint terminates a running execution.
Request (DELETE):
curl -X DELETE -u 'username:password' http://bf5:8080/api/<api_version>/execution/<execution_id>
If the request is successful an empty response with status code 200 will be returned.
Delete execution¶
This endpoint deletes an execution from the database, terminating it if it is running.
Request (DELETE):
curl -u 'username:password' http://bf5:8080/api/<api_version>/execution/delete/<execution_id>
If the request is successful an empty response with status code 200 will be returned.
List all executions¶
This endpoint will list all executions belonging to the calling user. If the user has an administrator role, executions for all users will be returned.
Request (GET):
curl -u 'username:password' http://bf5:8080/api/<api_version>/execution
Will return a JSON document like this:
{
"25152" : {
"time_submit" : 1473337122.87461,
"id" : 25152,
[...]
"status" : "running",
"time_start" : 1473337156.8096,
"services" : [
26768
],
"time_end" : null,
"name" : "boinc-loader",
"error_message" : null
},
"25086" : {
"time_start" : 1473337123.30892,
"status" : "running",
"user_id" : "venzano",
[..]
It is a map with the execution IDs as keys and the full execution details as values.
Starting from verion 0.7 of the API, the execution list can be filtered.
You need to pass via the URL (GET parameters) the criteria to be used for filtering, for example:
curl -u 'username:password' http://bf5:8080/api/<api_version>/execution?status=terminated\&limit=1
Valid criteria that can be used are:
- status: one of submitted, scheduled, starting, error, running, cleaning up, terminated
- name: execution mane
- user_id: user_id owning the execution (admin only)
- limit: limit the number of returned entries
- earlier_than_submit: all execution that where submitted earlier than this timestamp
- earlier_than_start: all execution that started earlier than this timestamp
- earlier_than_end: all execution that ended earlier than this timestamp
- later_than_submit: all execution that where submitted later than this timestamp
- later_than_start: all execution that started later than this timestamp
- later_than_end: all execution that started later than this timestamp
All timestamps should be passed as number of seconds since the epoch (UTC timezone).
Start execution¶
Request (POST):
curl -X POST -u 'username:password' --data-urlencode @filename http://bf5:8080/api/<api_version>/execution
Needs a JSON document passed as the request body:
{
"application": <zapp json>,
'name': "experiment #33"
}
Where:
application
is the full ZApp JSON document, the application descriptionname
is the name of the execution provided by the user
Will return a JSON document like this:
{
"execution_id": 23441
}
Where:
execution_id
is the ID of the new execution just created.
Service endpoint¶
All the endpoints listed in this section require authentication.
Service details¶
Request:
curl -u 'username:password' http://bf5:8080/api/<api_version>/service/<service_id>
Will return a JSON document like this:
{
"status" : "active",
"service_group" : "boinc-client",
"backend_status" : "started",
"ip_address" : "10.0.0.94",
"execution_id" : 25158,
"name" : "boinc-client0",
"backend_id" : "d0042c69b54e90327d9287e099304b6c25921d81f639803494ea744445d58430",
"error_message" : null,
"id" : 26774,
"description" : {
[...]
}
}
Where:
status
is the service status from Zoe point of view. It can be one of “terminating”, “inactive”, “active” or “starting”service_group
is the name for the service provided in the ZApp description. When the ZApp is unpacked to create the actual containers a single service definition will spawn one or more services with this name in commonbackend_status
is the container status from the point of view of the container backend. Zoe tries her best to keep this value in sync, but the value here can be out of sync by several minutes. It can be one of ‘undefined’, ‘created’, ‘started’, ‘dead’ or ‘destroyed’ip_address
is the IP address of the containerexecution_id
is the execution ID this service belongs toname
is the name for this service instance, generated fromservice_group
backend_id
is the ID used by the backend to identify this containererror_message
is currently unusedid
is the ID of this service, should match the one given in the URLdescription
is the service description extracted from the ZApp
Service standard output and error¶
Request:
curl -u 'username:password' http://bf5:8080/api/<api_version>/service/logs/<service_id>
Will stream the service instance output, starting from the time the service started. It will close the connection when the service exits.
Discovery endpoint¶
This endpoint does not need authentication. It returns a list of services that meet the criteria passed in the URL. It can be used as a service discovery mechanism for those ZApps that need to know in advance the list of available services.
Request:
curl http://bf5:8080/api/<api_version>/discovery/by_group/<execution_id>/<service_type>
Where:
execution_id
is the numeric ID of the execution we need to queryservice_type
is the service name (as defined in the ZApp) to filter only services of that type
Will return a JSON document, like this:
{
"service_type" : "boinc-client",
"execution_id" : "23015",
"dns_names" : [
"boinc-client0-23015-prod"
]
}
Where:
service_type
is the name of the service as passed in the URLexecution_id
is the execution ID as passed in the URLdns_names
is the list of DNS names for each service instance currently active (only one in the example above)
Statistics endpoint¶
This endpoint does not need authentication. It returns current statistics about the internal Zoe status.
Scheduler¶
Request:
curl http://bf5:8080/api/<api_version>/statistics/scheduler
Will return a JSON document, like this:
{
"termination_threads_count" : 0,
"queue_length" : 0
}
Where:
termination_threads_count
is the number of executions that are pending for termination and cleanupqueue_length
is the number of executions in the queue waiting to be started
OAuth2 endpoint¶
This endpoint aims to help users authenticate/authorize via an access token instead of raw username/password. It does need authentication when users require new access token. You can refresh an access token by a refresh token.
Request new access token¶
Request:
curl -u 'username:password' http://bf5:8080/api/<api_version>/oauth/token -X POST -H 'Content-Type: application/json' -d '{"grant_type": "password"}'
Will return a JSON document, like this:
{
"token_type": "Bearer",
"access_token": "3ddbe9ba-6a21-4e4d-993b-70556390c5d3",
"refresh_token": "9bab190f-e211-42aa-917e-20ce987e355e",
"expires_in": 36000
}
Where:
token_type
is the type of the token, Bearer is used as defaultaccess_token
is the token used for further authentication/authorization with others api endpointsrefresh_token
is the token used to get new access token when the current one has expiredexpires_in
is the duration of time (second) when the access_token would be expired
Refresh an access token¶
Request:
curl -H 'Authorization: Bearer 9bab190f-e211-42aa-917e-20ce987e355e' http://bf5:8080/api/<api_version>/oauth/token -X POST -H 'Content-Type: application/json' -d '{"grant_type": "refresh_token"}'
Will return a JSON document, like this:
{
"token_type": "Bearer",
"access_token": "378f8d5f-2eb5-4181-b632-ad23c4534d32",
"expires_in": 36000
}
Where:
access_token
is the new access token after users issue a refresh
Revoke an access/refresh token¶
Request:
curl -u 'usernam:password' -X DELETE http://bf5:8080/api/<api_version>/oauth/revoke/<token>
Where:
token
is the access token or refresh token needs to be revoked
Will return a JSON document, like this:
{
"ret": "Revoked token."
}
Authenticate other api endpoint¶
Instead of sending raw username, password to request results from other api endpoints which require authentication, use an access token with header Authorization: Bearer <token>
Example:
curl -H 'Authorization: Bearer 378f8d5f-2eb5-4181-b632-ad23c4534d32' http://bf5:8080/api/<api_version>/execution
Login endpoint¶
Get back a cookie for further authentication/authorization with other api endpoints instead of using raw username, password
Request:
curl -u 'username:password' -c zoe_cookie.txt http://bf5:8080/api/<api_version>/login
Will return a JSON document, like this:
{
"role": "admin",
"uid": "admin"
}
And a file named zoe_cookie.txt contains the cookie information.
Pass this cookie on each api request which requires authentication.
Example:
curl -b zoe_cookie.txt http://bf5:8080/api/<api_version>/execution
Note:
- For zoe web interface, we require cookie_based mechanism for authentication/authorization.
- Every unauthorized request will be redirected to http://bf5:8080/login
- After successfully login, a cookie will be saved at browser for further authentication/authorization purpose.