API v1 spec
rewrite of the spec in .MD format to better support clean code blocks. moved into approved folder Change-Id: Ida36a618cfeb5a5097cd88bbb09e6b15c8f8f9a1 storyboard: https://storyboard.openstack.org/#!/story/132
This commit is contained in:
david
parent
e3ad76adad
commit
799323e224
225
specs/approved/api-v1.md
Executable file
225
specs/approved/api-v1.md
Executable file
@ -0,0 +1,225 @@
|
||||
Refstack API v1
|
||||
===============
|
||||
This document is to serve as the complete spec for refstack's v1 api.
|
||||
|
||||
###Problem description#
|
||||
|
||||
As our requirements grow, so must the api. To maintain backwards compatibility on a live running copy of the api we have to version it to insure that older software can still have basic api functionality.
|
||||
|
||||
This api will be implemented at api.refstack.org. Current api functions that exist in web.py will be deprecated as software that relies on them are updated to use the new api.
|
||||
|
||||
###Proposed change#
|
||||
|
||||
This isn't so much a change as a definition of the api that has evolved so far. This way we have a v1 spec and can use it to plan for v2 features and changes.
|
||||
|
||||
###Alternatives#
|
||||
|
||||
N/A
|
||||
|
||||
###REST API impact#
|
||||
|
||||
All urls will be prefaced by */v1/* indicating version one of the api is in use.
|
||||
|
||||
####events#
|
||||
|
||||
**description:** allows remote tester to add and list events of a test run.
|
||||
|
||||
**url:** post: /v1/events/
|
||||
|
||||
**parameters:**
|
||||
|
||||
str:data - a string input containing json as shown in lower example.
|
||||
|
||||
**post example:**
|
||||
|
||||
{
|
||||
'job_id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'message': 'this job has failed because of blah',
|
||||
'event_type': 'finished'|'failed'|'pending'|'running'
|
||||
}
|
||||
|
||||
**sucessful response:** http:201 - The status has been saved
|
||||
|
||||
{
|
||||
'id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'job_id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'timestamp': '00:00:00',
|
||||
'message': 'this job has failed because of blah',
|
||||
'event_type': 'finished'|'failed'|'pending'|'running'
|
||||
}
|
||||
|
||||
**failed response:** http:404 - the job_id doesn't exist
|
||||
|
||||
{
|
||||
'message': 'the job_id does not exist',
|
||||
}
|
||||
|
||||
**failed response:** http:400 - malformed request | missing information
|
||||
|
||||
{
|
||||
'message': 'malformed request | missing information',
|
||||
}
|
||||
|
||||
------------
|
||||
|
||||
####jobs > events#
|
||||
|
||||
**description:** Allows remote tester to add events to a test run.
|
||||
|
||||
**url:** get: /v1/jobs/[job_id]/events
|
||||
|
||||
**Parameters:**
|
||||
|
||||
int:job_id - The test id you want the event history for.
|
||||
|
||||
**sucessful response:** http:201 - here are some results
|
||||
|
||||
[{
|
||||
'id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'job_id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'timestamp': '00:00:00',
|
||||
'message': 'the job is starting',
|
||||
'event_type': 'pending'
|
||||
},
|
||||
{
|
||||
'id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'job_id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'timestamp': '00:00:01',
|
||||
'message': 'tests are running now',
|
||||
'event_type': 'running'
|
||||
},
|
||||
{
|
||||
'id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'job_id': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'timestamp': '00:00:02',
|
||||
'message': 'this job has finsihed',
|
||||
'event_type': 'finished'
|
||||
}]
|
||||
|
||||
**failed response:** http:404 - the job_id doesn't exist
|
||||
|
||||
{
|
||||
'message': 'the job_id doesnt exist.'
|
||||
}
|
||||
|
||||
------------
|
||||
|
||||
####results#
|
||||
|
||||
**description:** Receive tempest test result from a remote test runner. this function expects json formated pass results.
|
||||
|
||||
**url:** post /v1/results
|
||||
|
||||
**parameters:**
|
||||
|
||||
str:data - a string input containing json as shown in lower example.
|
||||
|
||||
**post example:**
|
||||
|
||||
{
|
||||
'cpid': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'duration_seconds': 23445234,
|
||||
'job_id': '3fd4e1c67a2d28fced849ee1bb76e7391b93eb13', /*optional*/
|
||||
'results': {} /* to be defined */
|
||||
}
|
||||
|
||||
**normal response:** http:201 - the status has been saved
|
||||
|
||||
{
|
||||
'id': '7fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'cpid': '2fd4e1c67a2d28fced849ee1bb76e7391b93eb12',
|
||||
'duration_seconds': 23445234,
|
||||
'job_id': '3fd4e1c67a2d28fced849ee1bb76e7391b93eb13'
|
||||
/* if posted without job_id this will contain the test id that was created */
|
||||
}
|
||||
|
||||
**failed response:** http:404 - the job_id does not exist
|
||||
|
||||
{
|
||||
'message': 'the job_id does not exist.'
|
||||
}
|
||||
|
||||
**failed response:** http:400 - the job_id already has results
|
||||
|
||||
{
|
||||
'message': 'the job_id already has results'
|
||||
}
|
||||
|
||||
**Data model impact**
|
||||
|
||||
* add int field called duration_seconds to test model
|
||||
* add varchar field cpid to test model
|
||||
* change name of subunit field in test model to results and possibly increase length
|
||||
* change name of TestStatus to Events
|
||||
* add int field event_type to Events model
|
||||
|
||||
**Security impact**
|
||||
|
||||
* Does this change touch sensitive data such as tokens, keys, or user data? **no**
|
||||
|
||||
* Does this change alter the API in a way that may impact security, such as a new way to access sensitive information or a new way to login? **yes**
|
||||
|
||||
_we have not implemented a security model around reporting events. some discussion will need to take place to decide if this is acceptable._
|
||||
|
||||
* Does this change involve cryptography or hashing? **no**
|
||||
|
||||
* Does this change require the use of sudo or any elevated privileges? **no**
|
||||
|
||||
* Does this change involve using or parsing user-provided data? This could
|
||||
be directly at the API level or indirectly such as changes to a cache layer. **yes**
|
||||
|
||||
_we will be parsing results and json data being posted to perform different actions and will therefore be vulnerable. in order to protect ourselves we will have to take care with the parsing code to ensure things are valid and not open to injection attacks_
|
||||
|
||||
* Can this change enable a resource exhaustion attack, such as allowing a single API interaction to consume significant server resources? Some examples of this include launching subprocesses for each connection, or entity expansion attacks in XML. **no**
|
||||
|
||||
|
||||
**Notifications impact**
|
||||
|
||||
N/A
|
||||
|
||||
**Other end user impact**
|
||||
|
||||
Moving forward any changes to the testing client will need to be in sync with the api version.
|
||||
|
||||
**Performance Impact**
|
||||
|
||||
N/A
|
||||
|
||||
**Developer impact**
|
||||
|
||||
This will effect a lot of areas of existing code.. this is why the second work item below is "update exising api calls and web views so that they are compatible with the new scema" and "modify testing client to use the new api calls".
|
||||
|
||||
**Implementation:**
|
||||
|
||||
The api will be implemented as a flask application in the api.py file.
|
||||
|
||||
**Assignee(s)**
|
||||
|
||||
Primary assignee:
|
||||
dlenwell
|
||||
|
||||
**Work Items**
|
||||
|
||||
* update models to reflect above mentioned schema changes.
|
||||
* update exising api calls and web views so that they are compatible with the new scema.
|
||||
* replace current api.py with a new api that meets this spec.
|
||||
* create validation decorator
|
||||
* stand up api.refstack.org with new api.
|
||||
* write api unit tests.
|
||||
* modify testing client to use the new api calls.
|
||||
|
||||
**Dependencies**
|
||||
|
||||
N/A
|
||||
|
||||
**Testing**
|
||||
|
||||
* we will require api unit tests for each call and expected response.
|
||||
|
||||
**Documentation Impact**
|
||||
|
||||
* all api functions will have sphinx compatible doc tags reflecting actual usage.
|
||||
|
||||
**References**
|
||||
|
||||
N/A
|
||||
@ -1,180 +0,0 @@
|
||||
===============
|
||||
Refstack API v1
|
||||
===============
|
||||
This document is to serve as the complete spec for refstacks v1 api.
|
||||
|
||||
**Problem description**
|
||||
|
||||
As our requirements grow, so must the api. To maintain backwards compatibility
|
||||
on a live running copy of the api we have to version it to insure that older
|
||||
software can still have basic api functionality.
|
||||
|
||||
**Proposed change**
|
||||
|
||||
This isn't so much a change as a definition of the api that has evolved so far.
|
||||
This way we have a v1 spec and can use it to plan for v2 features and changes.
|
||||
|
||||
**Alternatives**
|
||||
|
||||
I am open to suggestions on better ways to maintain working older clients with
|
||||
also allowing the api to evolve.
|
||||
|
||||
**Data model impact**
|
||||
|
||||
none.
|
||||
|
||||
**REST API impact**
|
||||
|
||||
All urls will be prefaced by */v1/* indicating version one of the api is in use.
|
||||
|
||||
------------
|
||||
|
||||
``update-test-status``
|
||||
|
||||
**method:** *post*
|
||||
|
||||
**description:** allows remote tester to update the status of a job that was
|
||||
triggered by the api.
|
||||
|
||||
**normal http response:** 201 - the status has been saved
|
||||
|
||||
**error http response:** 400 - either the test-id doesn't exist or the message
|
||||
was empty.
|
||||
|
||||
**url:** */v1/update-test-status/*
|
||||
|
||||
**Parameters:**
|
||||
|
||||
int:test_id - passed in the url (will take out of url)
|
||||
|
||||
bool:finished - boolean - indicates if job is finished yet.
|
||||
|
||||
str:status - posted string
|
||||
|
||||
**Example:**
|
||||
|
||||
*curl --data "status=test complete" http://refstack.org/v1/update-test-status/100*
|
||||
|
||||
------------
|
||||
|
||||
``post-result``
|
||||
|
||||
**method:** *post*
|
||||
|
||||
**description:** Receive tempest test result from a remote test runner. this function should be able to receive raw binary subunit files as well as json formated parsed results. The parsed results format will be useful for cloud operators who want to share results without security concerns.
|
||||
|
||||
**normal http response:** 201 - the status has been saved
|
||||
|
||||
**error http response:** 400 - the file value wasn't posted
|
||||
|
||||
**url:** */v1/post-result*
|
||||
|
||||
**Parameters:**
|
||||
|
||||
int:test_id - posted string, optional, leaving this out will write the results to the
|
||||
database as anonymous data.
|
||||
|
||||
blob:file - posted string
|
||||
|
||||
------------
|
||||
|
||||
``get-miniconf``
|
||||
|
||||
**method:** *get*
|
||||
|
||||
**description:** Return a JSON of mini tempest conf to a remote test runner.
|
||||
|
||||
**normal http response:** 200 filename=miniconf.json
|
||||
|
||||
**error http response:** 400 - Invalid test ID
|
||||
|
||||
**url:** */v1/get-miniconf*
|
||||
|
||||
**Parameters:**
|
||||
|
||||
int:test_id - tells refstack which cloud to grab extra config options for.
|
||||
|
||||
------------
|
||||
|
||||
**API methods to be deprecated**
|
||||
|
||||
`* no methods will be removed until they are no longer needed.`
|
||||
|
||||
get-script - this will no longer be needed if we package and version the test executer.
|
||||
|
||||
get-testcases - this will no longer be needed because the tester will just run all the tests.. period.
|
||||
|
||||
**Security impact**
|
||||
|
||||
* Does this change touch sensitive data such as tokens, keys, or user data? **no**
|
||||
|
||||
* Does this change alter the API in a way that may impact security, such as
|
||||
a new way to access sensitive information or a new way to login? **no**
|
||||
|
||||
* Does this change involve cryptography or hashing? **no**
|
||||
|
||||
* Does this change require the use of sudo or any elevated privileges? **no**
|
||||
|
||||
* Does this change involve using or parsing user-provided data? This could
|
||||
be directly at the API level or indirectly such as changes to a cache layer. **maybe
|
||||
the accept results method could use some tightening up**
|
||||
|
||||
* Can this change enable a resource exhaustion attack, such as allowing a
|
||||
single API interaction to consume significant server resources? Some examples
|
||||
of this include launching subprocesses for each connection, or entity
|
||||
expansion attacks in XML. **no**
|
||||
|
||||
|
||||
**Notifications impact**
|
||||
|
||||
N/A
|
||||
|
||||
**Other end user impact**
|
||||
|
||||
Moving forward any changes to the testing client will need to be in sync with
|
||||
the api version.
|
||||
|
||||
**Performance Impact**
|
||||
|
||||
N/A
|
||||
|
||||
**Developer impact**
|
||||
|
||||
This will change the way the current docket templated tester installs the
|
||||
testing script. currently it pulls the script from an api call then runs
|
||||
it.. thats a nightmare security risk.. we can't leave the functionality so
|
||||
removing that method from the api v1 spec should address that.
|
||||
|
||||
**Implementation:**
|
||||
|
||||
**Assignee(s)**
|
||||
|
||||
Primary assignee:
|
||||
dlenwell
|
||||
|
||||
**Work Items**
|
||||
|
||||
* remove get-script method
|
||||
* organize all pure api calls into a different file.
|
||||
* add code to import the api functions when web.py is loaded.
|
||||
* update the existing api to have the correct HTTP response
|
||||
* add timeout and error reporting to update_status method
|
||||
|
||||
**Dependencies**
|
||||
|
||||
N/A
|
||||
|
||||
**Testing**
|
||||
|
||||
Since we currently have no tests this isn't an issue.. although perhaps we
|
||||
should write tests for our own stuff.. since you know testing is at the core
|
||||
of refstack.
|
||||
|
||||
**Documentation Impact**
|
||||
|
||||
Since we have not written docs for the api.. let this document serve as the
|
||||
starting place for that.
|
||||
|
||||
**References**
|
||||
|
||||
N/A
|
||||
Loading…
x
Reference in New Issue
Block a user