rest_api.md

TDS 2 REST API specification

Some quick notes:

• All data in requests and responses is in JSON
• All GET requests to resource type roots (e.g., /applications) return lists of matching resources. Well-behave clients should query URLs for specific resources (e.g, /applications/tds) when only that resource is desired rather than query the resource root or searching for that resource with a query.

Terminology

• Collection URL: The URL for interacting with collections of resources (e.g., /applications)
• Individual URL: The URL for interacting with a single known resource (e.g., /applications/tds)

LDAP integration

This API integrates with LDAP for authentication and authorization. Post to /login with your LDAP login credentials to receive a session cookie to be used for the duration of your session. Session cookies are valid, as of 2016-02-04, for 15 days since time of issuance. All requests other than to /login throw a 401: Unauthorized without LDAP authentication.

Methods Overview

DELETE

Returns nothing for successful DELETE requests.

GET

All 200 responses to GET requests are:

• lists of matching objects for resource collection URLs.
• JSON objects for individual resource URLs.

POST

POST requests run queries to see if any unique constraints will be violated by a potential write to the database before doing the actual write. They also check for the validity of foreign key relationships. As a result, POST requests will throw a 403: Forbidden error in this case.

PUT

PUT requests can only be made to individual resources currently.

Routing

The URLs and methods will be the same for /projects, /ganglias, /hipchats, /hosts, /tiers, /deployments, /host_deployments, and /tier_deployments as for /applications below. URLs and methods will also be the same for /projects/NAME as for /applications/NAME below.

Path-Method Table

URL	Method	Operation	Request	Response
/applications	GET	Retrieve the full details, including the unique IDs, for all applications	'limit': Number of applications to return. 'start': Starting position for returned queries, by ID. If 'start' = 10, then all applications with ID >= 10 will be returned.	200: Return all matching applications. Can be empty list. 401: Authentication required. Cookie not present, valid, and/or unexpired. 422: Unprocessable entity. Illegal attributes or malformed JSON most likely.
	POST	Create a new applications.	Attributes for the new application. See Attributes section below for details.	201: Application created. Return application JSON. 400: Bad request. 401: Authentication required. Cookie not present, valid, and/or unexpired. 403: Forbidden. Lack of permissions. 409: Conflict. Unique constraint violated. Check errors in response for specifics.
/applications/NAME_OR_ID	DELETE	Delete the application with name or ID NAME_OR_ID.	None	204: Application deleted. Nothing to return. 301: Moved permanently. Renamed most likely. Return the new URI, as per HTTP/1.1. 401: Authentication required. Cookie not present, valid, and/or unexpired. 403: Forbidden. Lack of permissions. 404: Not found.
	GET	Retrieve the application with the name or ID NAME_OR_ID.	None	200: Return application. 301: Moved permanently. This may be hard to implement. We would need a column for former names for applications. 400: Bad request. 401: Authentication required. Cookie not present, valid, and/or unexpired. 404: Not found. 410: Gone. The application has been deleted. This may be hard to implement. We would need a table for deleted applications.
	PUT	Update application with name or ID NAME_OR_ID with new attributes.	New attributes to set for the application. See the Attributes section below for details.	200: Application updated. Return new attributes. 301: Moved permanently. 400: Bad request. 401: Authentication required. Cookie not present, valid, and/or unexpired. 403: Forbidden. Lack of permissions. 404: Not found. 409: Conflict. Unique constraint violated.
/applications/NAME_OR_ID/packages	GET	Get all packages for the application with name or ID NAME_OR_ID, paginated by 'limit' or 'start', optionally.	'limit': Number of packages to return. 'start': Starting position for returned queries, by ID. If 'start' = 10, then all packages with ID >= 10 will be returned.	200: Packages found and returned. 401: Authentication required. Cookie not present, valid, and/or unexpired. 404: No such application found. 422: Bad query.
	POST	Add a new package for the given application with the given attributes.	Attributes for the new package. See the Attributes section below for details.	201: Package created. Return package JSON. 400: Bad request. 401: Authentication required. Cookie not present, valid, and/or unexpired. 403: Forbidden. Lack of permissions. Check errors in response for specifics. 409: Conflict. Unique constraint violated.
/applications/NAME_OR_ID/packages/VERSION/REVISION	DELETE	Get the package with version VERSION, revision REVISION for application with name or ID NAME_OR_ID.	None	204: Package delete. Nothing to return. 401: Authentication required. Cookie not present, valid, and/or unexpired. 404: Application or package not found. See errors in response for specifics.
	GET	Delete the given package.	None	200: Return package. 401: Authentication required. Cookie not present, valid, and/or unexpired. 404: Not found.
	PUT	Update this package.	New attributes for this package. See the Attributes section below for details.	200: Package updated. 400: Bad request. See errors in response for specifics. Most likely a bad query. 401: Authentication required. Cookie not present, valid, and/or unexpired. 404: Not found. 409: Conflict. Unique constraint violated.
/login	POST	Get an auth cookie.	None, but body must be a valid JSON object with attributes "username" and "password".	200: Success. Cookie attached to response with name 'session'. 400: Bad request. See errors in response for specifics. Most likely a bad query. 422: Unprocessable entity. 401: Authentication failed.
/tiers/NAME_OR_ID/hipchats	GET	Get all HipChats associated with the tier with name or ID NAME_OR_ID.	None. NOTE: this URL does not supported limit or start queries	200: OK. HipChats returned. 404: Tier not found. 422: Unprocessable entity. This status will be returned for queries that include the limit or start parameters.
	POST	Associate an existing HipChat with the tier with name or ID NAME_OR_ID.	'id': ID of the HipChat to associate. Takes precedence over name. 'name': Name of the HipChat to associate. Gives precedence to ID.	200: OK. The HipChat was already associated with the tier. 201: Created. The HipChat was successfully associated with the tier. 400: Either 'name' or 'id' must be provided in the query. 404: Either the tier or the HipChat does not exist. 422: Unprocessable entity.
/tiers/NAME_OR_ID/hipchats/HIPCHAT_NAME_OR_ID	DELETE	Delete a Tier-HipChat association.	200: HipChat disassociated from tier. HipChat returned. 404: Tier or tier-HipChat association does not exist.
	GET	Get a HipChat that is associated with the given tier.	None	200: OK. HipChat returned. 404: Tier or tier-HipChat association does not exist.

Attributes

Timestamps

Timestamps are represented in the format YYYY-mm-ddTHH:MM:SS.SSSSSS+HHOO, where:

• YYYY - four digit year.
• mm - two digit month.
• dd - two digit day.
• HH - two digit hour.
• MM - two digit minute.
• SS.SSSSSS - float seconds
• HH - two digit hour offset from UTC.
• OO - two digit minute offset from UTC.

So the datetime for 3:14:15.926535PM PST, 30 January 2015 would be represented by 2015-01-30T15:14:15.926535+0000.

Parsing from Python UTC datetimes to timestamps:

import datetime
now = datetime.datetime.utcnow()
json_timestamp = now.isoformat() + '+0000'

Converting from timestamps to Python UTC datetimes:

date_format = "%Y-%m-%dT%H:%M:%S"
now = datetime.datetime.strptime(json_timestamp[:19], date_format)
rem = float(js[19:26]) + int(js[26:29]) * 3600 + int(js[29:31]) * 60
now += datetime.timedelta(seconds=rem)

The fractions of seconds are lost in translation from Python datetimes to UNIX timestamps but it is of little consequence as MySQL also strips second fractions off timestamps. The data presented by the API and the data present in the database is therefore identical.

Attribute Table

This table describes attributes of JSON objects mapped from the corresponding objects in Python.

Resource	Attribute	Type	Description	Example
Application	'id'	Integer	Unique integer ID for this application.	16
	'name'	String	Unique name for this application.	'tds'
	'job'	String	Path on the build server to application's builds.	'tds-tds-gauntlet'
	'build_host'	String	FQDN of the build host for this application.	'ci.tagged.com'
	'build_type'	String	Type of build system. Choices: 'developer', 'hudson', 'jenkins'.	'jenkins'
	'deploy_type'	String	Type of package system.	'rpm'
	'arch'	String	Architecture of application's packages.	'noarch'
	'validation_type'	String	The validation type for this application.	'user'
	'env_specific'	Boolean	Whether this application is environment-specific.	True
Ganglia	'id'	Integer	Unique integer ID for this Ganglia.	80
	'name'	String	Unique string identifier for this Ganglia.	'ganglia1'
	'port'	Integer	Port for this Ganglia	986
HipChat	'id'	Integer	Unique integer ID for this HipChat	34
	'name'	String	Unique name for this HipChat	'hipchat1'
Host	'id'	Integer	Unique integer ID for this host	34
	'name'	String	Unique name for this host	'host1'
	'tier_id'	Integer	Foreign key to a tier	5
	'cage'	Integer	Cage location for this host	10
	'cab'	String	Cab location for this host	'some_cab'
	'rack'	Integer	Rack location for this host	32
	'kernel_version'	String	Kernel version running on this host	'3.19.0-15-generic'
	'elevation'	Integer	Elevation within rack	'some_port'
	'power_port'	String	Power port for this host	'some_port'
	'power_circuit'	String	Power circuit for this host	'some_circuit'
	'state'	String	Choice of: 'baremetal', 'operational', 'repair', 'parts', 'reserved', 'escrow'	'operational'
	'arch'	String	Choice of: 'i386', 'noarch', 'x86_64'	'noarch'
	'distribution'	String	Choice of: 'centos5.4', 'centos6.2', 'centos6.4', 'centos6.5', 'centos7.0', 'centos7.1', 'fedora18', 'rhel5.3', 'rhel6.2', 'rhel6.3', 'rhel6.4', 'rhel6.5', 'ontap'	'centos7.1'
	'timezone'	String	Timezone for this host	'PST'
	'environment_id'	Integer	ID of this host's environment	1
Package	'id'	Integer	Unique integer ID for this package.	20
	'name'	String	Name for this package.	'tds'
	'version'	Integer	Package version.	22
	'revision'	Integer	Package revision.	24
	'status'	String	Status of this package in TDS. Choices: 'completed', 'failed', 'pending', 'processing', 'removed'.	'completed'
	'builder'	String	Build type for this package. Choices: 'developer', 'hudson', 'jenkins'.	'jenkins'
Project	'id'	Integer	Unique integer ID for this project	18
	'name'	String	Unique name for this project	'tds'
Tier	'id'	Integer	Unique integer ID for this tier	23
	'name'	String	Name identifying this tier	'tier1'
	'distribution'	String	Choice of: 'centos5.4', 'centos6.2', 'centos6.4', 'centos6.5', 'centos7.0', 'centos7.1', 'fedora18', 'rhel5.3', 'rhel6.2', 'rhel6.3', 'rhel6.4', 'rhel6.5', 'ontap'	'centos7.1'
	'puppet_class'	String	Puppet class for this tier	'baseclass'
	'ganglia_id'	Integer	ID for the ganglia for this tier	1
	'ganglia_name'	String	Ganglia name	'some_ganglia_thing'
	'status'	String	Choice of: 'active', 'inactive'	'active'
	'hipchats'	Integers	Array of HipChat IDs for this tier	1
Deployment	'id'	Integer	Unique integer ID for this deployment	46
	'package_id'	Integer	Package being deployment with this deployment	23
	'status'	String	Choice with only 'pending', 'queued', 'canceled' available to clients	'queued'
Host Deployment	'id'	Integer	Unique integer ID for this host deployment	23
	'deployment_id'	Integer	ID of the deployment to which this host deployment belongs	46
	'host_id'	Integer	ID of the host target for this host deployment	23
	'status'	String	Choice with only 'pending' available to clients	'pending'
Tier Deployment	'id'	Integer	Unique integer ID for this tier deployment	23
	'deployment_id'	Integer	ID of the deployment to which this tier deployment belongs	24
	'tier_id'	Integer	ID of the tier target for this tier deployment	23
	'status'	String	Choice with only 'pending' available to clients	'pending'
	'environment_id'	Integer	ID of the environment in which the host targets of this tier reside	1

---

rest_api.md: Copyright 2016 Ifwe Inc.

rest_api.md is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

You should have received a copy of the license along with this work. If not, see http://creativecommons.org/licenses/by-sa/4.0/.