REST API¶

This section documents the REST API of orlo, which is used to record release information and return information about releases.

GET /info/packages/versions¶

Return current version of all packages

Query Parameters:
	platform (bool) – Filter versions by platform by_release (bool) – If true, a package that is part of a release, which is not SUCCESSFUL, will not be considered the current version, even if its own status is SUCCESSFUL. If false, a package will be the current version as long as its own status is SUCCESSFUL. Default: False.

GET /info/packages/list¶

Return list of all known packages

Query Parameters:
	platform – Platform to filter on

GET /internal/version¶: Get the running version of Orlo :return:

GET /releases/import¶

Display a useful message on how to import

Status Codes:	200 OK –

POST /releases/import¶

Import a release.

This endpoint is designed to created releases in bulk. It bypasses the normal workflow, and may be an option for those who wish to “publish” a release after the fact rather than step through as it happens.

The document must contain a list of full releases, in json format. Example:

[
    {
        "platforms": [
          "GumtreeUK"
        ],
        "stime": "2015-12-17T17:02:04Z",
        "ftime": "2015-12-17T17:02:24Z",
        "team": "Gumtree UK Site Operations",
        "references": [
          "TICKET-1"
        ],
        "notes": [
          "Imported from other_system"
        ],
        "packages": [
            {
                "name": "",
                "diff_url": null,
                "stime": "2015-12-17T17:02:22Z"
                "ftime": 1450371742,
                "rollback": false,
                "status": "SUCCESSFUL",
                "version": "1.0.1",
            }
        ],
        "user": "user_one"
    },
    {...}
]

Timestamps can be any format understood by Arrow (note mix of unix time and ISO timestamps above).

Status must be one of the enums accepted by orlo.orm.Package.status, i.e.: NOT_STARTED, IN_PROGRESS, SUCCESSFUL, FAILED

A json null value is acceptable for non-required fields, or it can be omitted entirely. See orlo.orm.Release and orlo.orm.Package.

Example curl:

curl -v -X POST -d @releases.json 'http://127.0.0.1:5000/releases/import' -H         "Content-Type: application/json"

Status Codes:	200 OK – The document was accepted

GET /stats/platform/(platform)¶

GET /stats/platform¶

Return a dictionary of statistics for a platform name (optional), or all platforms

Query Parameters:
Parameters:	platform (string) – The platform name to provide stats for
	stime (string) – The lower bound of the time period to filter on ftime (string) – The upper bound of the time period to filter on

stime and ftime both filter on the release start time. Note that standard orlo API filters can be used here as well, not just stime/ftime

GET /stats/package/(package)¶

GET /stats/package¶

Return a dictionary of statistics for a package name (optional), or all packages

Query Parameters:
Parameters:	package (string) – The package name to provide p_stats for
	stime (string) – The lower bound of the time period to filter on ftime (string) – The upper bound of the time period to filter on

stime and ftime both filter on the release start time. Note that standard orlo API filters can be used here as well, not just stime/ftime

GET /stats/user/(username)¶

GET /stats/user¶

Return a dictionary of statistics for a username (optional), or all users

Query Parameters:
Parameters:	username (string) – The username to provide u_stats for
	stime (string) – The lower bound of the time period to filter on ftime (string) – The upper bound of the time period to filter on

stime and ftime both filter on the release start time. Note that standard orlo API filters can be used here as well, not just stime/ftime

GET /stats/team/(team)¶

GET /stats/team¶

Return a dictionary of statistics for a team (optional), or all teams

Query Parameters:
Parameters:	team (string) – The team name to provide t_stats for
	stime (string) – The lower bound of the time period to filter on ftime (string) – The upper bound of the time period to filter on

stime and ftime both filter on the release start time.

GET /info/platforms/(platform)¶

GET /info/platforms¶

Return a summary of the platforms

Parameters:	platform – Platform to get info for

GET /info/packages/(package)¶

GET /info/packages¶

Summary of packages

Query Parameters:
Parameters:	package – Package to get info for
	platform – Platform to filter on

GET /info/users/(username)¶

GET /info/users¶

Return a dictionary of users optionally filtering by platform

Query Parameters:
Parameters:	username – Username to get info for
	platform – Platform to filter on

GET /packages/(package_id)¶

GET /packages¶

Return a list of packages to the client

Parameters:	package_id –
Return:

POST /releases¶

Create a release - the first step in a deployment

Request JSON Object:
	user (string) – User that is performing the release team (string) – The development team responsible for this release platforms (array) – List of platforms receiving the release references (array) – List of external references, e.g. Jira ticket
Response JSON Object:
	id (string) – UUID reference to the created release
Request Headers:
	Content-Type – Must be application/json
Status Codes:	200 OK – Release was created successfully 400 Bad Request – Invalid request

Example curl:

curl -H "Content-Type: application/json" \
-X POST \
http://127.0.0.1/releases \
-d '{"note": "blah", "platforms": ["site1"], "references": ["ticket"],
"team": "A-Team", "user": "aforbes"}'

GET /releases/(release_id)¶

GET /releases¶

Return a list of releases to the client, filters optional

Parameters:

release_id (string) – Optionally specify a single release UUID to fetch. This does not disable filters.

Query Parameters:

asc (bool) – Normally results are returned ordered by stime descending, setting asc to true will reverse this and sort by stime ascending
limit (int) – Limit the results by int (default 100)
offset (int) – Offset the results by int
user (string) – Filter releases by user the that performed the release
platform (string) – Filter releases by platform
stime_before (string) – Only include releases that started before timestamp given
stime_after (string) – Only include releases that started after timestamp given
ftime_before (string) – Only include releases that finished before timestamp given
ftime_after (string) – Only include releases that finished after timestamp given
team (string) – Filter releases by team
status (string) – Filter by release status. This field is calculated from the package status, see special note below.
duration_lt (int) – Only include releases that took less than (int) seconds
duration_gt (int) – Only include releases that took more than (int) seconds
package_rollback (boolean) – Filter on whether or not the releases contain a rollback
package_name (string) – Filter by package name
package_version (string) – Filter by package version
package_duration_gt (int) – Filter by packages of duration greater than
package_duration_lt (int) – Filter by packages of duration less than
package_status (string) – Filter by package status. Valid statuses are: “NOT_STARTED”, “IN_PROGRESS”, “SUCCESSFUL”, “FAILED”

Note for time arguments:: The timestamp format you must use is specified in /etc/orlo/orlo.ini. All times are UTC.
Note on status:: The release status is calculated from the packages it contains. The possible values are the same as a package. For a release to be considered “SUCCESSFUL” or “NOT_STARTED”, all packages must have this value. If any one package has the value “IN_PROGRESS” or “FAILED”, that status applies to the whole release, with “FAILED” overriding “IN_PROGRESS”.

GET /version¶: Display version information :return:

GET /token¶: Get a token

GET /stats¶

Return dictionary of global stats

Query Parameters:
	stime (string) – The lower bound of the time period to filter on ftime (string) – The upper bound of the time period to filter on

GET /ping¶

Simple ping test, takes no parameters

Example curl:

curl -X GET 'http://127.0.0.1/ping'

GET /info¶: Root of /info

GET /¶: Root page, display info

POST /releases/(release_id)/packages/(package_id)/results¶

Post the results of a package release

Request JSON Object:
Parameters:	release_id (string) – Release UUID package_id (string) – Package UUID
	content (string) – Free text field to store what you wish
Status Codes:	204 No Content – Package results added successfully

POST /releases/(release_id)/packages/(package_id)/start¶

Indicate that a package has started deploying

Parameters:	release_id (string) – Release UUID package_id (string) – Package UUID
Status Codes:	204 No Content –

Example curl:

curl -X POST http://127.0.0.1/releases/${RELEASE_ID}/packages/${
PACKAGE_ID}/start

POST /releases/(release_id)/packages/(package_id)/stop¶

Indicate that a package has finished deploying

Example curl:

curl -H "Content-Type: application/json" \
-X POST \
http://127.0.0.1/releases/${RELEASE_ID}/packages/${PACKAGE_ID}/stop \
-d '{"success": "true"}'

Parameters:	package_id (string) – Package UUID release_id (string) – Release UUID

POST /releases/(release_id)/packages¶

Add a package to a release

Request JSON Object:
Parameters:	release_id (string) – UUID of the release to add the package to
	name (string) – Name of the package version (string) – Version of the package rollback (boolean) – Whether this package deploy is a rollback
Response JSON Object:
	id (string) – UUID reference to the created package
Request Headers:
	Content-Type – Must be application/json
Status Codes:	200 OK – Package was added to the release successfully 400 Bad Request – Invalid request

Example curl:

curl -H "Content-Type: application/json" \
-X POST http://127.0.0.1/releases/${RELEASE_ID}/packages \
-d '{"name": "test-package", "version": "1.0.1"}'

POST /releases/(release_id)/metadata¶

Add metadata to a release

Query Parameters:
Parameters:	release_id (string) – Release UUID
	text (string) – Text
Return:

POST /releases/(release_id)/start¶

Indicate that a release is starting

Parameters:	release_id –
Return:

POST /releases/(release_id)/notes¶

Add a note to a release

Query Parameters:
Parameters:	release_id (string) – Release UUID
	text (string) – Text
Return:

POST /releases/(release_id)/stop¶

Indicate that a release has finished

This should be called after all packages have also been “stopped”. In future it may stop any un-stopped packages.

Parameters:	release_id (string) – Release UUID

Example curl:

curl -H "Content-Type: application/json" \
-X POST http://127.0.0.1/releases/${RELEASE_ID}/stop

GET /stats/by_date/(subject)¶

Return stats by date

Query Parameters:
Parameters:	subject – Release or Package (default: release)
	unit (string) – Unit to group by, i.e. year, month, week, day, hour summarize_by_unit (boolean) – Don’t build hierarchy, just summarize by the unit
Return:

This endpoint also allows filtering on the same fields as GET /releases, e.g stime_gt. See that endpoint for documentation.

REST API¶

orlo

Navigation

Related Topics