From a0e6643a1dfa40cb5a1f94dc6f364057fd80c946 Mon Sep 17 00:00:00 2001 From: MrJoshua Date: Thu, 13 Mar 2014 13:59:00 -0700 Subject: [PATCH] Addided basic API docs. Updated readme with contribution instrucitons. Change-Id: I384a4dbfe9966dc8d07b748df9906aa95012a659 --- README.md | 70 +++++++++++++- apiary.apib | 262 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 331 insertions(+), 1 deletion(-) create mode 100644 apiary.apib diff --git a/README.md b/README.md index 047db51..90c6beb 100644 --- a/README.md +++ b/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" + "Joshua Kolden" + + ## 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. diff --git a/apiary.apib b/apiary.apib new file mode 100644 index 0000000..1ef9b0d --- /dev/null +++ b/apiary.apib @@ -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