Skip to content

Instantly share code, notes, and snippets.

@gschueler
Created December 17, 2010 02:04
Show Gist options
  • Save gschueler/744366 to your computer and use it in GitHub Desktop.
Save gschueler/744366 to your computer and use it in GitHub Desktop.

RunDeck REST API

Proposal.

API requests

path: /api/

Requests are made to the RunDeck server URL under the /api/ path. This path doesn't require the normal authentication to the server, but requires that a valid API Key be provided with each request. If one is not provided, then a response of 403: Unauthorized will be returned.

Requests can specify one of two output formats: XML or JSON.

The output format is determined by the extension provided to the request, e.g.:

/api/events/list.xml

Authentication:

Authentication is provided by API Keys, generated for particular users. A user with a particular set of access privs can generate an API Key for themselves that allows access in read-only, or read-write fashion.

Requests to the server must provide a valid API key.

The API Key can be provided as a HTTP header, or as a query parameter:

X-RunDeck-Auth-Key: <key>

Or as a query:

.../api/something?rdkey=<key>

Generating an API Key

A user can generate an API key for themselves by going to the User Profile page, and click ing "Generate API Key". Once a key is generated they can view it on their user Profile page and copy it from there.

Users can also invalidate any API key they own to remove it.

API

The available data is organized in four sections:

Jobs

API base path: /api/jobs/

Available actions:

Format:

XML: (See jobs-v10.xml.) JSON: (See jobs-v10.json)

List Jobs

Path: /api/jobs/list.ext

Query parameters: (query)

Results:

The result will be a list of all jobs matching the criteria.

Example:

http://localhost:4440/api/jobs/list.xml

Returns all jobs in XML format.

Show Job Detail

Path: /api/jobs/show//.ext

Query parameters: none

Results

The result will be the single job definition matching the criteria, or 404: Not Found if the job was not found.

Example:

http://localhost:4440/api/jobs/show/12.json

Returns the Job with ID 12 in JSON format.

Executions

API base path: /api/executions/

Resources

API base path: /api/resources/

Events

API base path: /api/events/

@noahcampbell
Copy link

The auth key is fine, but it implies SSL otherwise it's a bit loose.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment