with IBM Corp. · Storage API documentation, see OpenStack Object Storage API . See the Manager REST API Developer Guide for mor e information about managing a system pr ogrammatically

IBM Cloud Object Storage System™

Version 3.14.3

OpenStack Object Storage API 1.0Guide

IBM

This edition applies to IBM Cloud Object Storage System™ and is valid until replaced by new editions.

© Copyright IBM Corporation 2016, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Document Information . . . . . . . . v

Chapter 1. API overview . . . . . . . . 1Comparison of supported APIs . . . . . . . . 1Differences between OpenStack and IBM CloudObject Storage System OSOS APIs . . . . . . . 1

Chapter 2. Deployment, configuration,and use . . . . . . . . . . . . . . . 3Configure IBM Cloud Object Storage System to useOpenStack . . . . . . . . . . . . . . . 3OSOS API usage . . . . . . . . . . . . . 3

Chapter 3. Supported subset. . . . . . 5Common request headers . . . . . . . . . . 5

Common response headers . . . . . . . . . 5Authentication. . . . . . . . . . . . . . 5Storage account services . . . . . . . . . . 6Storage container services . . . . . . . . . . 7Storage object services . . . . . . . . . . . 8

Notices . . . . . . . . . . . . . . 11

Trademarks. . . . . . . . . . . . . 13

Homologation statement . . . . . . . 15

© Copyright IBM Corp. 2016, 2019 iii

iv OSOS API 1.0 Guide

Document Information

Intended Purpose and Audience

The OpenStack Object Storage (OSOS) Application Programming Interface (API) enables applicationdevelopers to use existing OpenStack applications to access object vaults on an IBM Cloud Object StorageSystem™.

© Copyright IBM Corp. 2016, 2019 v

vi OSOS API 1.0 Guide

Chapter 1. API overview

The OpenStack Object Storage (OSOS) Application Programming Interface (API) enables applicationdevelopers to use existing OpenStack applications to access object vaults on an IBM Cloud Object StorageSystem™.

IBM Cloud Object Storage System™ supports dispersed storage object APIs, with some functionaldifferences between them.

Comparison of supported APIsA REST API is available as part of the Dispersed Storage Object (DSO) API Family.

Table 1. Supported Dispersed Storage Object APIs

REST API Write Mode Listings Store User Metadata Compatibility

Simple Object HTTP Write-by-ID Recovery Only

Cloud Storage Object Write-by-Name Prefix-based NameSearch and RecoveryListing

Yes Amazon S3v2006-03-01

OpenStack ObjectStorage

Write-by-Name Prefix-based NameSearch and RecoveryListing

Yes OpenStack v1.0

Like any REST API in the DSO API Family, the OSOS API is automatically deployed on any IBM CloudObject Storage Accesser®. Any object vault that is deployed can be access through any API in the APIFamily.

The IBM Cloud Object Storage System™ implementation of the OSOS API supports the most commonlyused subset of OpenStack API operations that are implemented by the reference OpenStack software. Thisdocument highlights differences between these two implementations. It should be used in combinationwith the OpenStack Object Storage Developer Guide – API v1.

Table 2. Write Modes for Object Storage APIs

Mode Description

write-by-name A client specifies an object name when performing a write operation by using theOSOS API. Objects that are written by name can also read by that name.

write-by-id A client does not specify an object name when performing a write by using theSimple Object HTTP API. Instead, the client writes data and the server assigns anobject ID, which is returned when the write is complete. This method is slightly lowerlatency than write-by-name as it does not involve the internal name index.

Differences between OpenStack and IBM Cloud Object StorageSystem™ OSOS APIsHighlights of functional differences between the OpenStack API and OSOS API.

Table 3. Functional differences between OpenStack and OSOS APIs

Function OpenStack OSOS

Object Size Limitations 5 GB Storing objects larger than 100 GB is notrecommended.

© Copyright IBM Corp. 2016, 2019 1

Table 3. Functional differences between OpenStack and OSOS APIs (continued)

Function OpenStack OSOS

Object Segmentation Support v Segment objects greater than 5GB before upload.

v A manifest object is also createdto track the segments thatbelong to a large object.

v Object segmentation is unsupported.

v Objects greater than 5 GB can beuploaded in a single request.

Version Support v Does not support object versions.

v Data is removed from the systemimmediately when an object is deleted.

Retention Policy Supported Unsupported

Create/Delete Container Vaults are created and deleted by using theManager.

Containers are created via the Swift API.

Create/Delete/Modify Account Accounts are created via the Service API.

Accounts are managed by using theManager.

Create Static Website Static Web Middleware via swift is notsupported.

Supports HTTP BasicAuthentication

Clients can use either OpenStack V1token-based authentication, OpenStackKeystone [V2 or V3 if enabled], or RFC1945 HTTP Basic Authentication.

Cross-Container Copy Object COPY operations are supported, butonly when the source and destinationobjects reside within the same vault.

2 OSOS API 1.0 Guide

Chapter 2. Deployment, configuration, and use

Configure IBM Cloud Object Storage System™ to use OpenStackBefore using this API, configure these features by using the Configure Provisioning API section in theManager Administration Guide.

OSOS API usageWhen an object vault is deployed to an Accesser® Appliance, it is automatically made available througheach of the REST APIs in the DSO API Family.

Clients can always access the OSOS API via the following URL scheme:http://<accesser-ip>/openstack/v1/username/<container-name>/<object-name>

Where:

Table 4. OSOS API use

Path Component Description

accesser-ip The IP address or host name of the Accesser® Appliance. The actual address mightdiffer for client applications if a proxy or load balancer is being used.

openstack This literal indicates that the OSOS API is compatible with OpenStack.

v1 This literal indicates the version of the OSOS API.

username Username of a system account with access to the vault.

container-name The container that is accessed in the OpenStack API.

object-name The full object name that is being accessed. It is omitted for vault operations such aslisting.

If the OSOS API is configured as the Default API for an Accesser® Appliance, clients can also access theAPI via the following URL scheme:http://accesser-ip/v1/username/vault-name/object-name

Access through HTTPS is also supported.

Note: See the Manager Administration Guide for more information on deploying an object vault and SSLand PKI access through an Accesser® Appliance.



Chapter 3. Supported subset

Common request headersUnsupported headers are ignored if set in a request.

Table 5. Common request headers

Operation Supported Note

Authorization Yes BASIC authentication mechanism

Content-Length Yes Chunked encoding is supported also.

Content-Type Yes Stored as object metadata.

Host Yes Required for Authentication request.

X-Auth-Token Yes Can be token generated by an OpenStack Keystone V2 or V3server or a base 64 encoded string that is made of the basicauthentication credentials that are generated by the system if aKeystone server is not available.

Common response headersTable 6. Common response headers

Header Supported Note

Content-Length Yes

Connection Yes

Date Yes

ETag Yes Contains MD5 checksum.

Server Yes

Content-Type Yes Stored as object metadata.

Authentication

Unless otherwise noted in the table below, all parameters, operation-specific request and responseheaders, and response body are supported in conformance to the OpenStack API.

Table 7. Exceptions to Authentication Headers for OSOS API

Header Type Header Description

Request Host IP address or host name of Accesser® Appliance or configuredload balancer.

X-Auth-User Username of the system account with access to the vault. If aKeystone V2 or V3 server is configured to back authentication inthe manager, the username, separator, and domain (for example,username@domain) of the Keystone account with access to thevault.

X-Auth-Key Password of the system account with access to the vault. If aKeystone V2 or V3 server is configured to back authentication inthe manager, the password of the Keystone account with accessto the vault.


Table 7. Exceptions to Authentication Headers for OSOS API (continued)

Header Type Header Description

Response X-Storage-Url Host portion is read from Host request header and the accountis set to the username specified in the X-Auth-User requestheader.

X-Auth-Token If an OpenStack Keystone V2 or V3 server is configured to backauthentication in the manager, the response contains a Keystonegenerated token. If there is not a Keystone server that isconfigured, the token is a base 64 encoded string that containsbasic access authentication credentials that are associated withthe credentials that are specified in the X-Auth-User andX-Auth-Key request headers.

Note: For general information on OpenStack Object Storage API in the OpenStack Object Storage APIdocumentation, see Object Storage API overview.

Storage account services

The table describes the service operation that is supported in OSOS API.

Table 8. Supported service operations in OSOS API

Operation Supported

List Containers. Yes

Retrieve Account Metadata. Yes

Create or Update Account Metadata. No

Delete Account Metadata. No

The Manager REST API includes supports for:v Listing vaults on an entire systemv Listing vault deployments on a system by the Accesser® Appliance.

The Manager must be used for all vault configuration.

Note: For complete documentation on API operations for storage services in the OpenStack ObjectStorage API documentation, see OpenStack Object Storage API.

See the Manager REST API Developer Guide for more information about managing a systemprogrammatically.

List containers

All parameters, operation-specific request headers, operation-specific response headers, and responsebody are supported in conformance to the OpenStack API.

Retrieve account metadata



https://docs.openstack.org/developer/swift/api/object_api_v1_overview.html

https://developer.openstack.org/api-ref/object-storage/index.html

Storage container services

The table describes which container operations are supported in OSOS API. It also indicates someoperations that, while not supported, can be accomplished by using another mechanism such as theManager or are planned for inclusion in future API versions. AnyOpenStack API operation that is notpresent is not supported on a system through any API.

Table 9. Supported Container Operations in OSOS API


List Objects. Yes

Create Container. Yes

Delete Container. Yes

Get Container Metadata. Yes

Create or Update ContainerMetadata.

Yes

Delete Container Metadata. Yes

Note: For complete documentation on API operations for storage services in the OpenStack ObjectStorage API documentation, refer to OpenStack Object Storage API.

List objects


When Recovery Listing is enabled, the results of a List Objects operation are returned innon-lexigraphical order. However, pagination is supported by using the normal convention by using the“marker” parameter. The listing parameters “prefix”, “delimiter”, and “path” are not supported inrecovery listing mode.

If the name index is disabled for a vault and recovery mode listing is not enabled, all listing operationrequests result in an HTTP 405 Method Not Allowed response code.

Get container metadata

Unless otherwise noted in the table above, all parameters, operation-specific request headers,operation-specific response headers, and response body are supported in conformance to the OpenStackAPI.

Create or update container metadata


Delete container metadata


Chapter 3. Supported subset 7


Storage object services

The table describes the object operations that are supported in the OSOS API. It describes all operationson objects available as part of the OpenStack API. Versioning is not supported for any operation.

Table 10. Supported Object Operations in OSOS API


Get Object Details. Yes

Create or Update Object. Partial No large object segmentation support. Noretention policy

Assigning CORS Headers to Requests No

Enabling File Compression with the Content-EncodingHeader

Yes

Enabling Browser Bypass with the Content-DispositionHeader

Yes

Expiring Objects with the X-Delete-After andX-Delete-At Headers

No

Object Versioning No

Copy Object Yes

Delete Object. Yes

Get Object Metadata. Yes

Updated Object Metadata Yes

Note: For complete documentation on API operations for storage services in the OpenStack ObjectStorage API documentation, refer to OpenStack Object Storage API.

Get object details


Create or update object

Unless otherwise noted in the table below, all parameters, operation-specific request headers,operation-specific response headers, and response body are supported in conformance to the OpenStackAPI.

Table 11. Exceptions to Create or Update Object Headers in OSOS API

Header type Header Supported Note

Request headers X-Delete-At Ignored

X-Delete-After Ignored

X-Object-Manifest No HTTP 400 Bad Requesterror is returned.

Copy object

All parameters, operation-specific request headers, operation-specific response headers, and responsebody are supported in conformance to the S3 API.



CAUTION:Copying an object can result in significant bandwidth usage.

Delete object


Get object metadata


Update object metadata

Unless otherwise noted in the table below, all parameters, operation-specific request headers,operation-specific response headers, and response body are supported in conformance to the OpenStackAPI.

Table 12. Exceptions to Update Object Metadata Headers in OSOS API

Header type Header Supported

Request headers X-Delete-At Ignored

X-Delete-After Ignored

Chapter 3. Supported subset 9


Notices

This information was developed for products and services offered in the US. This material might beavailable from IBM® in other languages. However, you may be required to own a copy of the product orproduct version in that language in order to access it.

IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply thatonly that IBM product, program, or service may be used. Any functionally equivalent product, program,or service that does not infringe any IBM intellectual property right may be used instead. However, it isthe user's responsibility to evaluate and verify the operation of any non-IBM product, program, orservice.

IBM may have patents or pending patent applications covering subject matter described in thisdocument. The furnishing of this document does not grant you any license to these patents. You can sendlicense inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte character set (DBCS) information, contact the IBM IntellectualProperty Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOTLIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY ORFITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided for convenience only and do not inany manner serve as an endorsement of those websites. The materials at those websites are not part ofthe materials for this IBM product and use of those websites is at your own risk.

IBM may use or distribute any of the information you provide in any way it believes appropriate withoutincurring any obligation to you.


Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785US

Such information may be available, subject to appropriate terms and conditions, including in some cases,payment of a fee.

The licensed program described in this document and all licensed material available for it are providedby IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement orany equivalent agreement between us.

The performance data discussed herein is presented as derived under specific operating conditions.Actual results may vary.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice,and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject to change withoutnotice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.


Trademarks

IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International BusinessMachines Corp., registered in many jurisdictions worldwide. Other product and service names might betrademarks of IBM or other companies. A current list of IBM trademarks is available on the web atCopyright and trademark information at www.ibm.com/legal/copytrade.shtml.

Accesser®, Cleversafe®, ClevOS™, Dispersed Storage®, dsNet®, IBM Cloud Object Storage Accesser®, IBMCloud Object Storage Dedicated™, IBM Cloud Object Storage Insight™, IBM Cloud Object StorageManager™, IBM Cloud Object Storage Slicestor®, IBM Cloud Object Storage Standard™, IBM Cloud ObjectStorage System™, IBM Cloud Object Storage Vault™, SecureSlice™, and Slicestor® are trademarks orregistered trademarks of Cleversafe, an IBM Company and/or International Business Machines Corp.

Other product and service names might be trademarks of IBM or other companies.


http://www.ibm.com/legal/copytrade.shtml


Homologation statement

This product may not be certified in your country for connection by any means whatsoever to interfacesof public telecommunications networks. Further certification may be required by law prior to making anysuch connection. Contact an IBM representative or reseller for any questions.



IBM®

Printed in USA

Documents

with IBM Corp. · Storage API documentation, see OpenStack Object Storage API . See the Manager REST API Developer Guide for mor e information about managing a system pr ogrammatically