Difference between revisions of "Manila/API"
(→Create Share) |
(→List shares with details) |
||
Line 157: | Line 157: | ||
"snapshot_id": null, | "snapshot_id": null, | ||
"status": "available" | "status": "available" | ||
+ | "metadata": { | ||
+ | "key1": "value1", | ||
+ | "key2": "value2" | ||
+ | }, | ||
} | } | ||
] | ] |
Revision as of 10:47, 6 December 2013
Contents
This document describes how to develop applications that use Manila Service API v1 for authentication. This document also describes how to integrate services with Manila Service API v1.
Glossary
To use the Shared Filesystem Managenent service API effectively, you should understand several key concepts:
Share A remote mountable filesystem. It can only be attached to several instances at a time.
Share type Share protocol (NFS, CIFS)
Snapshot A point in time copy of the data contained in a share.
High-Level Task Flow
The high-level task flow for Manila is as follows:
The tenant creates a share. For example, the tenant creates a 30G NFS share called share1.
$ manila create --name share1 --description "Example of high-level taskflow" nfs 30
Authentication
You can use cURL to try the authentication process in two steps: get a token; send the token to a service. Get an authentication token by providing your user name and either your API key or your password. Here are examples of both approaches: You can request a token by providing your user name and your password.
$ curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
Successful authentication returns a token which you can use as evidence that your identity has already been authenticated. To use the token, pass it to other services as an X-Auth-Token header. Authentication also returns a service catalog, listing the endpoints you can use for Cloud services. Use the authentication token to send a GET to a service you would like to use. Authentication tokens are typically valid for 24 hours. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint.
Request/Response Types
Manila API supports both the JSON and XML data serialization formats. The request format is specified using the Content-Type header and is required for calls that have a request body. The response format can be specified in requests either by using the Accept header or by adding an .xml or .json extension to the request URI. Note that it is possible for a response to be serialized using a format different from the request. If no response format is specified, JSON is the default. If conflicting formats are specified using both an Accept header and a query extension, the query extension takes precedence.
Table 2.1. Response Formats
Format | Acceptt Header | Query Extension | Default |
---|---|---|---|
JSON | application/json | .json | Yes |
XML | application/xml | .xml | No |
API Operations
POST /v1/<tenant_id>/shares
Content-Type: application/json
Accept: application/json
JSON Request
{ "share": { "description": "Some description", "name": "test", "share_proto": "nfs", "size": 1, "metadata": { "key1": "value1", "key2": "value2" }, "snapshot_id": null } }
JSON Response
{ "share": { "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1", "links": [ { "href": "http://localhost:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1", "rel": "self" }, { "href": "http://localhost:8786/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1", "rel": "bookmark" } ], "name": "test" } }
GET /v1/<tenant_id>/shares/details
Accept: application/json
JSON Response
{ "shares": [ { "availability_zone": "nova", "created_at": "2013-10-01T13:21:08.000000", "description": "Some description", "export_location": "localhost:/opt/stack/data/manila/mnt/share-5d3b8062-8c94-4f43-9106-43d9f43d94f1", "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1", "links": [ { "href": "http://localhost:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1", "rel": "self" }, { "href": "http://localhost:8786/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1", "rel": "bookmark" } ], "name": "test", "share_proto": "NFS", "size": 1, "snapshot_id": null, "status": "available" }, { "availability_zone": "nova", "created_at": "2013-10-01T11:15:19.000000", "description": "Some description", "export_location": "localhost:/opt/stack/data/manila/mnt/share-e9ecd8eb-439d-4ffe-83ab-86467c96c5b8", "id": "e9ecd8eb-439d-4ffe-83ab-86467c96c5b8", "links": [ { "href": "http://localhost:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/e9ecd8eb-439d-4ffe-83ab-86467c96c5b8", "rel": "self" }, { "href": "http://localhost:8786/fa831edf91fb4802a5bf9f92fbd8a689/shares/e9ecd8eb-439d-4ffe-83ab-86467c96c5b8", "rel": "bookmark" } ], "name": "test2", "share_proto": "NFS", "size": 2, "snapshot_id": null, "status": "available" "metadata": { "key1": "value1", "key2": "value2" }, } ] }
GET /v1/<tenant_id>/shares/<share_id>
Accept: application/json
JSON Response
{ "share": { "availability_zone": "nova", "created_at": "2013-10-01T13:21:08.000000", "description": "Some description", "export_location": "localhost:/opt/stack/data/manila/mnt/share-5d3b8062-8c94-4f43-9106-43d9f43d94f1", "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1", "links": [ { "href": "http://localhost:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1", "rel": "self" }, { "href": "http://localhost2:8786/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1", "rel": "bookmark" } ], "name": "test", "share_proto": "NFS", "size": 1, "snapshot_id": null, "status": "available" } }
PUT /v1/<tenant_id>/shares/<share_id>
Accept: application/json
JSON Request
{ "share": { "display_description": "New description", "display_name": "newname" } }
JSON Response
{ "share": { "availability_zone": "nova", "created_at": "2013-10-02T09:58:12.000000", "description": "New description", "export_location": "localhost:/opt/stack/data/manila/mnt/share-ad18175b-d9fc-4d75-98de-0adba1992b8d", "id": "ad18175b-d9fc-4d75-98de-0adba1992b8d", "links": [ { "href": "http://localhost:8786/v1/23ccb90954c149ee8cb7de08521914be/shares/ad18175b-d9fc-4d75-98de-0adba1992b8d", "rel": "self" }, { "href": "http://localhost:8786/23ccb90954c149ee8cb7de08521914be/shares/ad18175b-d9fc-4d75-98de-0adba1992b8d", "rel": "bookmark" } ], "name": "newname", "share_proto": "NFS", "size": 2, "snapshot_id": null, "status": "available" } }
DELETE /v1/<tenant_id>/shares/<share_id>
Accept: application/json
Snapshots
Create Snapshot
POST /v1/<tenant_id>/snapshots
Accept: application/json
JSON Request
{ "snapshot": { "description": null, "force": false, "name": null, "share_id": "e1f9c138-f614-43a6-8a0c-51c39f3b169c" } }
JSON Response
{ "snapshot": { "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "links": [ { "href": "http://localhost:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "self" }, { "href": "http://localhost:8786/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "bookmark" } ], "name": null } }
List Snapshots with Details
GET /v1/<tenant_id>/snapshots/details
Accept: application/json
JSON Response
{ "snapshots": [ { "created_at": "2013-10-02T10:04:59.000000", "description": null, "export_location": "localhost:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c", "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "links": [ { "href": "http://localhost:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "self" }, { "href": "http://localhost:8786/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "bookmark" } ], "name": null, "share_id": "e1f9c138-f614-43a6-8a0c-51c39f3b169c", "share_proto": "NFS", "share_size": 1, "size": 1, "status": "available" } ] }
Show Snapshot
GET /v1/<tenant_id>/snapshots/<snapshot_id>
Accept: application/json
JSON Response
{ "snapshot": { "created_at": "2013-10-02T10:04:59.000000", "description": null, "export_location": "localhost:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c", "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "links": [ { "href": "http://localhost:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "self" }, { "href": "http://localhost:8786/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "bookmark" } ], "name": null, "share_id": "e1f9c138-f614-43a6-8a0c-51c39f3b169c", "share_proto": "NFS", "share_size": 1, "size": 1, "status": "available" } }
Update Snapshot
PUT /v1/<tenant_id>/snapshots/<snapshot_id>
Accept: application/json
JSON Request
{ "snapshot": { "display_description": "New description", "display_name": "newname" } }
JSON Response
{ "snapshot": { "created_at": "2013-10-02T10:04:59.000000", "description": "New description", "export_location": "localhost:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c", "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "links": [ { "href": "http://localhost:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "self" }, { "href": "http://localhost:8786/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c", "rel": "bookmark" } ], "name": "newname", "share_id": "e1f9c138-f614-43a6-8a0c-51c39f3b169c", "share_proto": "NFS", "share_size": 1, "size": 1, "status": "available" } }
Delete Snapshot
DELETE /v1/<tenant_id>/snapshots/<snapshot_id>
Accept: application/json
Extensions
Allow access
POST /v1/<tenant_id>/shares/<share_id>/action
Accept: application/json
JSON Request
{ "os-allow_access": { "access_to": "1.1.1.1", "access_type": "ip" } }
JSON Response
{ "access": { "access_to": "1.1.1.1", "access_type": "ip", "created_at": "2013-10-02T10:29:36.539532", "deleted": false, "deleted_at": null, "id": "ae3cd150-610e-4e8a-8e2c-e1c0c02d38ad", "share_id": "e1f9c138-f614-43a6-8a0c-51c39f3b169c", "state": "new", "updated_at": null } }
Deny Access
POST /v1/<tenant_id>/shares/<share_id>/action
Accept: application/json
JSON Request
{ "os-deny_access": { "access_id": "ae3cd150-610e-4e8a-8e2c-e1c0c02d38ad" } }
List Access Rules
POST /v1/<tenant_id>/shares/<share_id>/action
Accept: application/json
JSON Request
{ "os-access_list": null }
JSON Response
{ "access_list": [ { "access_to": "1.1.1.1", "access_type": "ip", "id": "f66ae7f2-7d12-4c5e-8ee8-aeef69b155fc", "state": "active" } ] }