Add documentation for the shipyard API.
Also added comments to the existing API documentation to indicate intentions going forward.
This commit is contained in:
Bryan Strassner
parent
0e68ce4f5b
commit
746812d700
164
docs/API.md
Normal file
164
docs/API.md
Normal file
@ -0,0 +1,164 @@
|
||||
# Shipyard API
|
||||
|
||||
Logically, the API has three parts to handle the three areas of functionality in Shipyard.
|
||||
|
||||
1. Document Staging
|
||||
2. Action Handling
|
||||
3. Scheduled Task Inquiry
|
||||
|
||||
There are several standard error responses that should be handled appropriately by a client of this API:
|
||||
* 401 Authentication Error if not authenticated
|
||||
* 403 Forbidden if not authorized
|
||||
* 503 Service Unavailable Error if an upstream system cannot be reached (e.g. Deckhand for documents, Airflow for actions)
|
||||
|
||||
## Document Staging API
|
||||
Shipyard will serve as the entrypoint for documents and secrets into a site. At any point in time, there will be two represented versions of documents in a site that are accessible via this API.
|
||||
|
||||
* The lastDeployed version, which represents the last version of documents that successfully completed deployment.
|
||||
* The staged version, which represents the document set that has been ingested by this API since the lastDeployed version.
|
||||
|
||||
|
||||
### /v1.0/configDocs
|
||||
Represents the site configuration documents.
|
||||
|
||||
#### POST
|
||||
Ingests site configuration documents. Synchronous.
|
||||
##### Responses
|
||||
200 OK: if the documents are successfully ingested, even with validation failures.
|
||||
Response message includes:
|
||||
* a link to the GET /configDocs
|
||||
* a list of validation results
|
||||
|
||||
#### GET
|
||||
Returns the source documents for the most recently staged version
|
||||
Query Parameter "lastDeployed=true" will insetead return the documents for the currently deployed version.
|
||||
##### Responses
|
||||
200 OK if documents can be retrieved.
|
||||
|
||||
##### DELETE
|
||||
Updates the configDocs to be the lastDeployed versions in deckhand, effectively discarding any staged documents.
|
||||
###### Responses
|
||||
204 No Content
|
||||
|
||||
|
||||
### /v1.0/secrets
|
||||
Represents the secrets documents that will be used in combination with the config docs.
|
||||
|
||||
##### POST
|
||||
Ingest new secrets documents.
|
||||
###### Responses
|
||||
201 Created: if the documents are successfully ingested, even with validation failures.
|
||||
Response message includes:
|
||||
* a link to the GET /configDocs
|
||||
* a list of validation results
|
||||
|
||||
#### GET
|
||||
Return the secrets documents
|
||||
##### Responses
|
||||
200 OK if documents can be retrieved.
|
||||
|
||||
#### DELETE
|
||||
Updates the secrets to be the lastDeployed versions in deckhand, effectively discarding any staged documents.
|
||||
##### Responses
|
||||
204 No Content
|
||||
|
||||
|
||||
## Action API
|
||||
Signal to Shipyard to take an action (e.g. Invoke a named DAG)
|
||||
Supported actions:
|
||||
* deploy region
|
||||
* update region
|
||||
* redeploy server
|
||||
* test region (invoke site validation testing - perhaps baseline is a invocation of all components regular "component" tests.
|
||||
* test component (invoke a particular component to test it?)
|
||||
|
||||
|
||||
### /v1.0/actions
|
||||
All actions will include fields that indicate the following data:
|
||||
* id (assigned during POST)
|
||||
* name - the name of the action - likely to be the DAG Names, but may be mapped for "nicer" values.
|
||||
* parameters - a dictionary of the parameters configuring the action.
|
||||
* tracking info (user, time, etc?)
|
||||
* action_lifecycle enum of [Pending, Validation Failed, In DAG, Complete, Failed] -- and potentially others...
|
||||
* DAG_status - representing the status that airflow provides for an executing DAG ? running, paused, failed, stopped
|
||||
* validations - a list of validaitons that have been done, including any status information for those validations. During the lifecycle of the DAG, this list of validations may continue to grow.
|
||||
* steps - the list of steps for this action, including the status for that step.
|
||||
|
||||
#### GET
|
||||
Returns the list of actions in the system that have been posted, and are accessible to the current user.
|
||||
Query parameter: targetId={target_id} - return only those triggers for the specified {target_id} (e.g. region)
|
||||
The response will be the same as the detailed response for each object, minus the validations and steps.
|
||||
##### Responses
|
||||
200 OK if the actions can be retrieved.
|
||||
|
||||
#### POST
|
||||
Creates an action in the system. This will cause some action to start.
|
||||
The input body to this post will represent an action object that has at least these fields:
|
||||
* name: the name of the action to invoke. This is likely to map to the actual DAG Names, but may be mapped for "nicer" values.
|
||||
* parameters: A dictionary of parameters to use for the trigger invocation. The supported parameters will vary for the action invoked.
|
||||
|
||||
The POST will synchrounously create the action (a shell object that represents a DAG invocation), perform any checks to validate the preconditions to run the DAG, and trigger the invocation of the DAG.
|
||||
The DAG will run Asynchrounously in airflow.
|
||||
##### Responses
|
||||
201 Created if the action is created successfully, and all preconditions to run the DAG are successful. The response body is the action entity created.
|
||||
400 Bad Request if the action name doesn't exist, or the payload is otherwise malformed.
|
||||
409 Conflict for any failed validations. The response body is the action entity created, with the failed validations. The DAG will not begin execution in this case.
|
||||
404 Not found if the target_id is not valid.
|
||||
503 If Airflow or other dependencies are not available
|
||||
|
||||
|
||||
### /v1.0/actions/{action_id}
|
||||
Each action will be assigned an unique id that can be used to get details for the action, including the execution status.
|
||||
|
||||
#### GET
|
||||
Returns the action entity for the specified id.
|
||||
##### Responses
|
||||
200 OK
|
||||
|
||||
|
||||
### /v1.0/actions/{action_id}/validationDetails/{validation_id}
|
||||
Allows for drilldown to validation detailed info.
|
||||
|
||||
#### GET
|
||||
Returns the validation detail by Id for the supplied action Id.
|
||||
##### Responses
|
||||
200 OK
|
||||
|
||||
|
||||
### /v1.0/actions/{action_id}/steps/{step_id}
|
||||
Allow for drilldown to step information. The step information includes details of the steps excution, successful or not, and enough to facilitate troubleshooting in as easy a fashion as possible.
|
||||
|
||||
#### GET
|
||||
Returns the details for a step by id for the given action by Id.
|
||||
##### Responses
|
||||
200 OK
|
||||
|
||||
|
||||
### /v1.0/actions/{action_id}/{control_verb}
|
||||
Allows for issuing DAG controls against an action.
|
||||
|
||||
#### POST
|
||||
Trigger a control action against an activity.- this includes: stop, pause, resume (need to determine the totality of this list)
|
||||
##### Responses
|
||||
202 Accepted
|
||||
|
||||
## Airflow Monitoring API
|
||||
Airflow has a primary function of scheduling DAGs, as opposed to the shipyard primary case of triggering DAGs. Shipyard will need to provide functionality to allow for an operator to monitor the scheduled tasks, both pending and previously run.
|
||||
|
||||
|
||||
### /v1.0/scheduledTasks
|
||||
The resource that represents scheduled tasks in airflow (Fields TBD)
|
||||
|
||||
#### GET
|
||||
Queries airflow for ?recent? completed tasks (a summary) and the schedule for the next pending executions of DAGs.
|
||||
Query parameter: elapsedDays, the number of days of history to retrieve. Default is 10 days.
|
||||
##### Responses
|
||||
200 OK
|
||||
|
||||
|
||||
#### /v1.0/scheduledTasks/{id}
|
||||
|
||||
##### GET
|
||||
Further details of a particular scheduled task's output
|
||||
###### Responses
|
||||
200 OK
|
||||
@ -1,3 +1,5 @@
|
||||
Please note that this API information is being superseded by a new client facing API (under development) This file will stay in place for now, but needs to be removed when the newer API is in place. Please see API.md for the newer information.
|
||||
|
||||
## REST API ##
|
||||
|
||||
The default deployment will build an environment where the Falcon API server listens on port 31901
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user