Proposal.
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 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>
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.
The available data is organized in four sections:
API base path: /api/jobs/
Available actions:
- List available jobs
- Show job detail
- [Update Job]
- [Delete Job]
- [Create Job]
- [Run Job]
Format:
XML: (See jobs-v10.xml.) JSON: (See jobs-v10.json)
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.
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.
API base path: /api/executions/
API base path: /api/resources/
API base path: /api/events/
The auth key is fine, but it implies SSL otherwise it's a bit loose.