Addided basic API docs. Updated readme with contribution instrucitons.
Change-Id: I384a4dbfe9966dc8d07b748df9906aa95012a659
This commit is contained in:
MrJoshua
parent
7476fffe84
commit
a0e6643a1d
70
README.md
70
README.md
@ -26,14 +26,82 @@ More information go to https://wiki.openstack.org/wiki/Milk
|
||||
|
||||
---
|
||||
|
||||
# Contributing
|
||||
|
||||
## Current Requirements
|
||||
|
||||
[git](http://git-scm.com)
|
||||
[Python3](http://www.python.org)
|
||||
[pip](https://pypi.python.org/pypi/pip)
|
||||
[git-review](http://www.mediawiki.org/wiki/Gerrit/git-review)
|
||||
[Django](https://www.djangoproject.com)
|
||||
[virtualenv](http://www.virtualenv.org)
|
||||
[freshen](https://github.com/rlisagor/freshen)
|
||||
|
||||
## Links
|
||||
|
||||
[GitHub](https://github.com/stackforge/milk)
|
||||
[Wiki](https://wiki.openstack.org/wiki/Milk)
|
||||
|
||||
## To Contribute
|
||||
|
||||
1. Create a Launchpad account
|
||||
https://login.launchpad.net/+new_account
|
||||
|
||||
2. Join the OpenStack Foundation free
|
||||
https://www.openstack.org/join
|
||||
(Use the email address you plan to use with git for code contributions)
|
||||
|
||||
3. Agree to the the Individual Contributor License agreement:
|
||||
https://review.openstack.org/#/settings/
|
||||
Look under "Agreements" on the left menu.
|
||||
|
||||
4. Add an SSH public key to your launchpad account
|
||||
https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair
|
||||
|
||||
5. Add the same SSH key to your OpenStack Foundation / Gerrit Identity as well
|
||||
https://review.openstack.org/#/settings/
|
||||
Look under "SSH Public Keys" on the left menu.
|
||||
|
||||
6. Add the same SSH keys to your GitHub account
|
||||
Be sure to configure git on your development machine as well if you haven't already.
|
||||
|
||||
$ git config --global user.name "Firstname Lastname"
|
||||
$ git config --global user.email "your_email@youremail.com"
|
||||
|
||||
7. Install git-review. (In addition to python3, and pip3 )
|
||||
|
||||
$ sudo pip install git-review
|
||||
|
||||
8. Clone the GitHub project
|
||||
|
||||
$ git clone https://github.com/stackforge/milk
|
||||
|
||||
9. Create a branch with a descriptive branch name to make your changes.
|
||||
|
||||
$ git co -b add_tests
|
||||
|
||||
10. Without merging your branch with master, submit it for review with git-review.
|
||||
|
||||
$ git review
|
||||
|
||||
11. Track your contributions
|
||||
https://review.openstack.org/#/
|
||||
|
||||
12. If necessary manually add a reviewer
|
||||
Click on your patch listed from #10 above enter one of the following names or emails in the "Add Reviewer" field, and click add.
|
||||
"Sean Robers" <seanrob@yahoo-inc.com>
|
||||
"Joshua Kolden" <joshua@studiopyxis.com>
|
||||
|
||||
|
||||
## Development Spin Up...
|
||||
|
||||
###Tasks
|
||||
|
||||
- [X] Initialize the project in OpenStack and Gerrit.
|
||||
- [X] Create a git project on GitHub.
|
||||
- [X] Create first draft Apiary blueprint for ETC ID system API.
|
||||
- [ ] Establish BDD system, and create initial acceptance tests.
|
||||
- [ ] Create first draft Apiary blueprint for ETC ID system API.
|
||||
- [ ] Build basic Django server to implement blueprint.
|
||||
- [ ] Create command line tool to generate asset ID, and publish to server, via API.
|
||||
|
||||
|
||||
262
apiary.apib
Normal file
262
apiary.apib
Normal file
@ -0,0 +1,262 @@
|
||||
FORMAT: 1A
|
||||
|
||||
# ETC Cound Framework Milk
|
||||
This is an initial template for the ETC Milk Cloud Production Framework API.
|
||||
In this form it is setup to define multiple experimental apis for live testing.
|
||||
|
||||
|
||||
# API Dev Root [/]
|
||||
Milk-Dev entry point. This entry point list all test APIs provided.
|
||||
|
||||
## Retrieve Entry Point [GET]
|
||||
|
||||
+ Response 200 (application/json)
|
||||
|
||||
{interfaces: [
|
||||
{
|
||||
type: "registery",
|
||||
name: "String API",
|
||||
version "1.0",
|
||||
description: "String API - Draft 1",
|
||||
path: "/string/v1"
|
||||
},
|
||||
{
|
||||
type: "reference",
|
||||
name: "C4 Referece",
|
||||
version "1",
|
||||
description: "Parts of the public C4 API",
|
||||
path: "/c4"
|
||||
}
|
||||
]}
|
||||
|
||||
# String API [/string/v1]
|
||||
Data Model (For Phase 1)
|
||||
|
||||
The following is a basic set of services to call the String metadata API. While
|
||||
the HTTP call will most likely use a JSON POST, this remains to be architected.
|
||||
We have included an example of the HTTP calli in the login API call. In addition,
|
||||
the return format will need to be determined as well.
|
||||
|
||||
# Group Users
|
||||
|
||||
| userID | password | userGUID | email |
|
||||
|--------|-------------|--------------------------------------|----------------|
|
||||
| dax | Password123 | 550e8400-e29b-41d4-a716-446655440000 | chris@daxcloud |
|
||||
|
||||
## User Login [/login]
|
||||
This is used to login to the String API for the first time. After Phase 1, we
|
||||
will use the Keystone authentication API. It returns a session token to be used
|
||||
for the remaining calls.
|
||||
|
||||
### Login [POST]
|
||||
|
||||
+ Request
|
||||
|
||||
{username: "dax", password: "Password123"}
|
||||
|
||||
+ Response 200 (application/json)
|
||||
|
||||
{
|
||||
userGUID: "550e8400-e29b-41d4-a716-446655440000",
|
||||
session_token: "12345678901234567890"
|
||||
}
|
||||
|
||||
|
||||
# Group Assets and Services
|
||||
The primary registration method to associate an asset ID with a service type and
|
||||
a URI for more information. The call takes an optional description for this
|
||||
association to be retrieved as part of the lookup. In addition, publicly
|
||||
available metadata key-value pairs can be registered through the optional
|
||||
metadataPairs structure, which is a JSON-encoded, square-bracketed, quoted list
|
||||
of data.
|
||||
|
||||
`success = associateAsset(assetHash, serviceToken, URI, description, metadataPairs)`
|
||||
|
||||
| assetHash | service | URI | description | metadata |
|
||||
|---------------------------------|---------|------------------------------------------------------|--------------------------------|-----------------------------------------------------|
|
||||
| 0d6dce44a124443d845af191c3d1b64 | 5 | https://my.service.com/lookup/blah?asset=%assetHash% | The parent owner of this asset | [“Original”, “True”], [“Color-corrected”, “False”], |
|
||||
| | | | and all of its derivatives is | [“Copyright”, “2014 USC ETC”] |
|
||||
| | | | the USC ETC. | |
|
||||
|
||||
|
||||
## Assets and Services Collection [/AssetsServices]
|
||||
### List [GET]
|
||||
|
||||
+ Response 200 (applicaiton/json)
|
||||
|
||||
[
|
||||
{
|
||||
assetHash: "0d6dce44a124443d845af191c3d1b64"
|
||||
service: 5
|
||||
URI: "https://my.service.com/lookup/blah?asset=%assetHash%"
|
||||
description: "The parent owner of this asset and all of its derivatives is the USC ETC."
|
||||
metadata: {
|
||||
Original: true,
|
||||
Color-corrected: false,
|
||||
Copyright: 2014 USC ETC
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
## Create [POST]
|
||||
|
||||
+ Request
|
||||
|
||||
+ Headers
|
||||
|
||||
Authorization: Token token="12345678901234567890"
|
||||
|
||||
+ Body
|
||||
|
||||
{
|
||||
assetHash: "0d6dce44a124443d845af191c3d1b64"
|
||||
service: 5
|
||||
URI: "https://my.service.com/lookup/blah?asset=%assetHash%"
|
||||
description: "The parent owner of this asset and all of its derivatives is the USC ETC."
|
||||
metadata: {
|
||||
Original: true,
|
||||
Color-corrected: false,
|
||||
Copyright: 2014 USC ETC
|
||||
}
|
||||
}
|
||||
|
||||
+ Response 201
|
||||
|
||||
## Assets and Services Member [/AssetsServices/{assetHash}]
|
||||
### Retrieve [GET]
|
||||
|
||||
+ Response 200 (application/json)
|
||||
|
||||
{
|
||||
assetHash: "0d6dce44a124443d845af191c3d1b64"
|
||||
service: 5
|
||||
URI: "https://my.service.com/lookup/blah?asset=%assetHash%"
|
||||
description: "The parent owner of this asset and all of its derivatives is the USC ETC."
|
||||
metadata: {
|
||||
Original: true,
|
||||
Color-corrected: false,
|
||||
Copyright: 2014 USC ETC
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
## Update [PUT]
|
||||
|
||||
+ Request
|
||||
|
||||
+ Headers
|
||||
|
||||
Authorization: Token token="12345678901234567890"
|
||||
|
||||
+ Body
|
||||
|
||||
{
|
||||
description: "Update description."
|
||||
}
|
||||
|
||||
+ Response 200
|
||||
|
||||
|
||||
## Destroy [DELETE]
|
||||
|
||||
+ Request
|
||||
|
||||
+ Headers
|
||||
|
||||
Authorization: Token token="12345678901234567890"
|
||||
|
||||
+ Response 200
|
||||
|
||||
|
||||
# Group Service Registry
|
||||
|
||||
| service | serviceName | serviceToken | serviceDescription |
|
||||
|---------|-----------------------|--------------|--------------------------------------------------|
|
||||
| 5 | Ownership Information | OWNER | This service type provides ownership information |
|
||||
| | | | about the asset. A non-parameter call to the URI |
|
||||
| | | | will provide more information on how to access |
|
||||
| | | | this service. |
|
||||
|
||||
## Assets and Services Collection [/ServiceRegistry]
|
||||
### List [GET]
|
||||
|
||||
+ Response 200 (applicaiton/json)
|
||||
|
||||
[
|
||||
{
|
||||
service: 5
|
||||
serviceName: "Ownership Information"
|
||||
serviceToken: "OWNER"
|
||||
serviceDescription: "
|
||||
This service type provides ownership information about the
|
||||
asset. A non-parameter call to the URI will provide more
|
||||
information on how to access this service.
|
||||
"
|
||||
}
|
||||
]
|
||||
|
||||
## Create [POST]
|
||||
|
||||
+ Request
|
||||
|
||||
+ Headers
|
||||
|
||||
Authorization: Token token="12345678901234567890"
|
||||
|
||||
+ Body
|
||||
|
||||
{
|
||||
service: 5
|
||||
serviceName: "Ownership Information"
|
||||
serviceToken: "OWNER"
|
||||
serviceDescription: "
|
||||
This service type provides ownership information about the
|
||||
asset. A non-parameter call to the URI will provide more
|
||||
information on how to access this service.
|
||||
"
|
||||
}
|
||||
|
||||
+ Response 201
|
||||
|
||||
## Assets and Services Member [/ServiceRegistry/{service}]
|
||||
### Retrieve [GET]
|
||||
|
||||
+ Response 200 (application/json)
|
||||
|
||||
{
|
||||
service: 5
|
||||
serviceName: "Ownership Information"
|
||||
serviceToken: "OWNER"
|
||||
serviceDescription: "
|
||||
This service type provides ownership information about the
|
||||
asset. A non-parameter call to the URI will provide more
|
||||
information on how to access this service.
|
||||
"
|
||||
}
|
||||
|
||||
## Update [PUT]
|
||||
|
||||
+ Request
|
||||
|
||||
+ Headers
|
||||
|
||||
Authorization: Token token="12345678901234567890"
|
||||
|
||||
+ Body
|
||||
|
||||
{
|
||||
serviceDescription: "Update serviceDescription."
|
||||
}
|
||||
|
||||
+ Response 200
|
||||
|
||||
|
||||
## Destroy [DELETE]
|
||||
|
||||
+ Request
|
||||
|
||||
+ Headers
|
||||
|
||||
Authorization: Token token="12345678901234567890"
|
||||
|
||||
+ Response 200
|
||||
Loading…
Reference in New Issue
Block a user