ECS 2.0 – Use the ECS Management REST API

Table of Contents

Introduction

This article describes how to access the ECS Management REST API, it describes how to authenticate with it, and provides a summary of the API paths. The ECS Management REST API enables the object store to be configured and managed. Once the object store is configured, subsequent object create, read, update, and delete operations are performed using the supported S3, EMC Atmos, or OpenStack Swift object protocols.

You can refer to the following topic to get an understanding of how to access the REST API and how to authenticate:

and the API paths are summarized in:

In addition, an API Reference is provided in:

The ECS Management REST API Reference is auto-generated from the source code and provides a reference for the methods available in the API.

Back to Top

Authenticate with the ECS Management REST API

ECS uses a token-based authentication system for all its REST API calls. Examples are provided for authentication with the ECS REST API, with cookies and without cookies.

Once a user is authenticated against ECS, an authentication token is returned and can be used to authenticate the user in subsequent calls.

  • An HTTP 401 code is returned if the client is automatically following redirects, indicating that you need to login and authenticate to obtain a new token.
  • An HTTP 302 code is returned if the client is not automatically following redirects. The 302 code directs the client to where to get re-authenticated.

You can retrieve and use authentication tokens by:

  • Saving the X-SDS-AUTH-TOKEN cookie from a successful authentication request and sending that cookie along in subsequent requests.
  • Reading the X-SDS-AUTH-TOKEN HTTP header from a successful authentication request and copying that header into any subsequent request.
The REST API is available on port :4443 and clients access ECS by issuing a login request in the form:
https://<ECS_IP>:4443/login

The ECS Management REST API Reference provides a description and complete list of parameters for the REST API methods used in this article.

Back to Top

Authenticate with AUTH-TOKEN

This example shows how to use authentication tokens by reading the X-SDS-AUTH-TOKEN http header from a successful authentication request and copying that header into a subsequent request. This example does not use cookies. The examples here are written in curl and formatted for readability.

This command executes a GET on the /login resource. The -u option indicates the user of basic authentication header. The user designation must be included in the request. Upon successful authentication, a HTTP 200 code is returned as well as the X-SDS-AUTH-TOKEN header containing the encoded token.

curl -L --location-trusted -k https://10.247.100.247:4443/login -u "root:ChangeMe" -v

> GET /login HTTP/1.1
> Authorization: Basic cm9vdDpDaGFuZ2VNZQ==
> User-Agent: curl/7.24.0 (i386-pc-win32) libcurl/7.24.0 OpenSSL/0.9.8t zlib/1.2.5
> Host: 10.247.100.247:4443
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Tue, 26 Nov 2013 22:18:25 GMT
< Content-Type: application/xml
< Content-Length: 93
< Connection: keep-alive
< X-SDS-AUTH-TOKEN: BAAcQ0xOd3g0MjRCUG4zT3NJdnNuMlAvQTFYblNrPQMAUAQADTEzODU0OTQ4NzYzNTICAAEABQA5dXJu
                    OnN0b3JhZ2VvczpUb2tlbjo2MjIxOTcyZS01NGUyLTRmNWQtYWZjOC1kMGE3ZDJmZDU3MmU6AgAC0A8=
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<loggedIn>
   <user>root</user>
</loggedIn>
* Connection #0 to host 10.247.100.247 left intact
* Closing connection #0
* SSLv3, TLS alert, Client hello (1):

The token can then be passed back in the next API call. You can copy the X-SDS-AUTH-TOKEN contents and pass it to the next request through curl's -H switch.

curl https://10.247.100.247:4443/object/namespaces
     -k 
     -H "X-SDS-AUTH-TOKEN: BAAcOHZLaGF4MTl3eFhpY0czZ0tWUGhJV2xreUE4PQMAUAQADTEzODU0OTQ4NzYzNTICAAEABQA5dXJu
                           OnN0b3JhZ2VvczpUb2tlbjpkYzc3ODU3Mi04NWRmLTQ2YjMtYjgwZi05YTdlNDFkY2QwZDg6AgAC0A8="
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<namespaces>
   <namespace>
     <id>ns1</id>
     <link rel="self" href="/object/namespaces/namespace/ns1"/>
     <names>ns1</name>
   </namespace>
</namespaces>
Back to Top

Authenticate with cookies

This example shows how to use authentication tokens by saving the cookie from a successful authentication request, then passing the cookie in a subsequent request. The examples here are written in curl and formatted for readability.

In this example, you specify the ?using-cookies=true parameter to indicate that you want to receive cookies in addition to the normal HTTP header. This curl command saves the authentication token to a file named cookiefile in the current directory.
curl -L --location-trusted -k https://<ECS_IP>:4443/login?using-cookies=true 
-u "root:Password" 
-c cookiefile 
-v 
		
The next command passes the cookie with the authentication token through the -b switch, and returns the user's tenant information.
curl -k https://10.247.100.247:4443/object/namespaces -b cookiefile -v 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<namespaces>
   <namespace>
     <id>ns1</id>
     <link rel="self" href="/object/namespaces/namespace/ns1"/>
     <names>ns1</name>
   </namespace>
</namespaces>
Back to Top

Logout

The logout API ends a session.

A given user is allowed a maximum of 100 concurrent authentication tokens. Past this limit, the system refuses any new connection for this user until tokens free up. They can free up by expiring naturally, or by explicitly calling this URI:

https://<ECS_IP>:4443/logout

If you have multiple sessions running simultaneously, this URI forces the termination of all tokens related to the current user.

GET https://<ECS_IP>:4443/logout?force=true

An example logout request follows.

Request
GET https://<ECS_IP>:4443/logout

X-SDS-AUTH-TOKEN:{Auth_Token}

Pass in the header or cookie with the authentication token to logout.

Response
HTTP 200

Back to Top

Whoami

An ECS user can view their own user name, tenant association, and roles using the whoami API call.

Request

GET https://<ECS_IP>:4443/user/whoami

Response

HTTP 200

GET /user/whoami
<user>
  <common_name>root</common_name>
  <distinguished_name/>
  <namespace/>
  <roles>
    <role>SYSTEM_ADMIN</role>
  </roles>
</user>
HTTP 200

GET /user/whoami
<user>
  <common_name>fred@corp.sean.com</common_name>
  <distinguished_name/>
  <namespace>ns1</namespace>
  <roles>
    <role>NAMESPACE_ADMIN</role>
  </roles>
</user>

This example shows the whoami output for the root user and for a user who has been assigned to the NAMESPACE_ADMIN role for the "ns1" namespace.

Back to Top

ECS Management REST API summary

The ECS Management REST API enables the ECS object store to be configured and managed.

The following table summarizes the ECS Management REST API.

Back to Top