Jump to: navigation, search

Difference between revisions of "Manila/API"

Line 9: Line 9:
  
 
'''Share'''
 
'''Share'''
A remote mountable filesystem. It can only be attached to several instances at a time.
+
A remote mountable filesystem. It can only be attached to several instances at a time.
 
'''Share type'''
 
'''Share type'''
Share protocol (NFS, CIFS)
+
Share protocol (NFS, CIFS)
 
'''Snapshot'''
 
'''Snapshot'''
 
A point in time copy of the data contained in a share.
 
A point in time copy of the data contained in a share.
Line 17: Line 17:
  
 
The high-level task flow for Manila is as follows:
 
The high-level task flow for Manila is as follows:
 
  
 
The tenant creates a share.
 
The tenant creates a share.
 
 
For example, the tenant creates a 30G NFS share called share1.
 
For example, the tenant creates a 30G NFS share called share1.
 
 
      
 
      
$ manila create --name share1 --description "Example of high-level taskflow" nfs 30
+
$ manila create --name share1 --description "Example of high-level taskflow" nfs 30
  
   
+
   
 
 
   
 
 
=== Authentication ===
 
=== Authentication ===
  
 
You can use cURL to try the authentication process in two steps: get a token; send the token to a service.
 
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:
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.
 
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'
 
 
    $ 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.
 
 
 
 
  
 +
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.
 
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.
  
Line 59: Line 44:
  
 
Table 2.1. Response Formats
 
Table 2.1. Response Formats
Format Accept Header Query Extension Default
+
{| class="wikitable"
JSON application/json .json Yes
+
|-
XML application/xml .xml No
+
! Format !! Acceptt Header !! Query Extension !! Default
 +
|-
 +
|JSON || application/json || .json || Yes
 +
|-
 +
| XML || application/xml || .xml || No
 +
|}
  
 
   
 
   
Line 72: Line 62:
 
Content-Type: application/json
 
Content-Type: application/json
 
Accept: application/json
 
Accept: application/json
 
 
   
 
   
  
 
JSON Request
 
JSON Request
  
{    "share": {     
+
{    "share": {     
 
         "description": "Some description",
 
         "description": "Some description",
 
         "name": "test",
 
         "name": "test",
Line 84: Line 73:
 
         "snapshot_id": null
 
         "snapshot_id": null
 
     }
 
     }
}
+
}
  
 
JSON Response
 
JSON Response
  
{
+
{
 
     "share": {
 
     "share": {
 
         "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1",
 
         "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1",
Line 103: Line 92:
 
         "name": "test"
 
         "name": "test"
 
     }
 
     }
}
+
}
 
List shares with details
 
List shares with details
  
Line 112: Line 101:
 
JSON Response
 
JSON Response
  
{
+
{
 
     "shares": [
 
     "shares": [
 
         {
 
         {
Line 159: Line 148:
 
         }
 
         }
 
     ]
 
     ]
}
+
}
  
 
   
 
   

Revision as of 10:49, 3 October 2013

OpenStack Shared Filesystem Management Service API v1 specification

This document describes how to develop applications that use theManila Service API v1 for authentication. This document also describes how to integrate services with theManila 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

Shares

Create Share

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,
       "snapshot_id": null
   }
}

JSON Response

{
   "share": {
       "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1",
       "links": [
           {
               "href": "http://172.18.198.52:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1",
               "rel": "self"
           },
           {
               "href": "http://172.18.198.52:8786/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1",
               "rel": "bookmark"
           }
       ],
       "name": "test"
   }
}

List shares with details

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": "172.18.198.52:/opt/stack/data/manila/mnt/share-5d3b8062-8c94-4f43-9106-43d9f43d94f1",
           "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1",
           "links": [
               {
                   "href": "http://172.18.198.52:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1",
                   "rel": "self"
               },
               {
                   "href": "http://172.18.198.52: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": "172.18.198.52:/opt/stack/data/manila/mnt/share-e9ecd8eb-439d-4ffe-83ab-86467c96c5b8",
           "id": "e9ecd8eb-439d-4ffe-83ab-86467c96c5b8",
           "links": [
               {
                   "href": "http://172.18.198.52:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/e9ecd8eb-439d-4ffe-83ab-86467c96c5b8",
                   "rel": "self"
               },
               {
                   "href": "http://172.18.198.52:8786/fa831edf91fb4802a5bf9f92fbd8a689/shares/e9ecd8eb-439d-4ffe-83ab-86467c96c5b8",
                   "rel": "bookmark"
               }
           ], lags.py module and replace it with oslo.conf library to re-use common infrastructure between the various projects.
           "name": "test2",
           "share_proto": "NFS",
           "size": 2,
           "snapshot_id": null,
           "status": "available"
       }
   ]
}


Show Share

GET /v1/<tenant_id>/shares/5aa119a8-d25b-45a7-8d1b-88e127885635 Accept: application/json

JSON Response

{

   "share": {
       "availability_zone": "nova",
       "created_at": "2013-10-01T13:21:08.000000",
       "description": "Some description",
       "export_location": "172.18.198.52:/opt/stack/data/manila/mnt/share-5d3b8062-8c94-4f43-9106-43d9f43d94f1",
       "id": "5d3b8062-8c94-4f43-9106-43d9f43d94f1",
       "links": [
           {
               "href": "http://172.18.198.52:8786/v1/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1",
               "rel": "self"
           },
           {
               "href": "http://172.18.198.52:8786/fa831edf91fb4802a5bf9f92fbd8a689/shares/5d3b8062-8c94-4f43-9106-43d9f43d94f1",
               "rel": "bookmark"
           }
       ],
       "name": "test",
       "share_proto": "NFS",
       "size": 1,
       "snapshot_id": null,
       "status": "available"
   }

}

Update Share

PUT /v1/<tenant_id>/shares/ad18175b-d9fc-4d75-98de-0adba1992b8d 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": "172.18.198.52:/opt/stack/data/manila/mnt/share-ad18175b-d9fc-4d75-98de-0adba1992b8d",
       "id": "ad18175b-d9fc-4d75-98de-0adba1992b8d",
       "links": [
           {
               "href": "http://172.18.198.52:8786/v1/23ccb90954c149ee8cb7de08521914be/shares/ad18175b-d9fc-4d75-98de-0adba1992b8d",
               "rel": "self"
           },
           {
               "href": "http://172.18.198.52:8786/23ccb90954c149ee8cb7de08521914be/shares/ad18175b-d9fc-4d75-98de-0adba1992b8d",
               "rel": "bookmark"
           }
       ],
       "name": "newname",
       "share_proto": "NFS",
       "size": 2,
       "snapshot_id": null,
       "status": "available"
   }

}

Delete Share

DELETE /v1/<tenant_id>/shares/ad18175b-d9fc-4d75-98de-0adba1992b8d 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://172.18.198.52:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
               "rel": "self"
           },
           {
               "href": "http://172.18.198.52: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": "172.18.198.52:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c",
           "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
           "links": [
               {
                   "href": "http://172.18.198.52:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
                   "rel": "self"
               },
               {
                   "href": "http://172.18.198.52: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/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c Accept: application/json

JSON Response

{

   "snapshot": {
       "created_at": "2013-10-02T10:04:59.000000",
       "description": null,
       "export_location": "172.18.198.52:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c",
       "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
       "links": [
           {
               "href": "http://172.18.198.52:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
               "rel": "self"
           },
           {
               "href": "http://172.18.198.52: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/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c 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": "172.18.198.52:/opt/stack/data/manila/mnt/share-e1f9c138-f614-43a6-8a0c-51c39f3b169c",
       "id": "3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
       "links": [
           {
               "href": "http://172.18.198.52:8786/v1/23ccb90954c149ee8cb7de08521914be/snapshots/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c",
               "rel": "self"
           },
           {
               "href": "http://172.18.198.52: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/3c5b3b68-75c4-412f-8a9c-7ced9df2ac6c Accept: application/json

Extensions

Share Actions

Allow access

POST /v1/<tenant_id>/shares/e1f9c138-f614-43a6-8a0c-51c39f3b169c/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/e1f9c138-f614-43a6-8a0c-51c39f3b169c/action Accept: application/json

JSON Request

{

   "os-deny_access": {
       "access_id": "ae3cd150-610e-4e8a-8e2c-e1c0c02d38ad"
   }

}

List Access Rules

POST /v1/<tenant_id>/shares/e1f9c138-f614-43a6-8a0c-51c39f3b169c/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"
       }
   ]

}