Difference between revisions of "GCat Service"

From Gcube Wiki
Jump to: navigation, search
(HTTP Methods)
(HTTP Methods)
Line 105: Line 105:
 
| Patch || PATCH || /{COLLECTION}/{INSTANCE_ID}  || 200 OK || N || Y
 
| Patch || PATCH || /{COLLECTION}/{INSTANCE_ID}  || 200 OK || N || Y
 
|-
 
|-
| <span id="delete">Delete</span> || DELETE || /{COLLECTION}/{INSTANCE_ID}  || 204 No Content || N || N [[#non_safe_delete| ]]
+
| <span id="delete">Delete</span> || DELETE || /{COLLECTION}/{INSTANCE_ID}  || 204 No Content || N || N [[#non_safe_delete| ]]
 
|-
 
|-
| Purge || PURGE || /{COLLECTION}/{INSTANCE_ID}  || 204 No Content || N || N[[#non_safe_delete| ]]
+
| Purge || PURGE || /{COLLECTION}/{INSTANCE_ID}  || 204 No Content || N || N[[#non_safe_delete| ]]
 
|-
 
|-
| Purge || DELETE || /{COLLECTION}/{INSTANCE_ID}?purge=true  || 204 No Content || N || N[[#non_safe_delete| ]]
+
| Purge || DELETE || /{COLLECTION}/{INSTANCE_ID}?purge=true  || 204 No Content || N || N[[#non_safe_delete| ]]
 
|}
 
|}
  
Line 121: Line 121:
 
* A method is '''''Idempotent''''' if the same operation repeated multiple times has the same side effect than using it one time. "''repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ''" [https://tools.ietf.org/html/rfc7231#section-4.2.2 https://tools.ietf.org/html/rfc7231#section-4.2.2].
 
* A method is '''''Idempotent''''' if the same operation repeated multiple times has the same side effect than using it one time. "''repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ''" [https://tools.ietf.org/html/rfc7231#section-4.2.2 https://tools.ietf.org/html/rfc7231#section-4.2.2].
  
[[#delete|]] <span id="non_safe_delete">Allamaraju</span><ref>Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010</ref> argues that DELETE idempotency should be accomplished client-side. The server should inform the client if a delete succeeded because the resource was really deleted or it was not found i.e., 404 Not Found error is suggested instead of 204 No Content. The latter situation should be treated as idempotent by the client.
+
[[#delete|]] <span id="non_safe_delete">Allamaraju</span><ref>Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010</ref> argues that DELETE idempotency should be accomplished client-side. The server should inform the client if a delete succeeded because the resource was really deleted or it was not found i.e., 404 Not Found error is suggested instead of 204 No Content. The latter situation should be treated as idempotent by the client.
 
this service.
 
this service.
 
For this reason, Science Catalogue does not provide idempotency for DELETE and PURGE operations.
 
For this reason, Science Catalogue does not provide idempotency for DELETE and PURGE operations.

Revision as of 12:26, 30 November 2018

The gCube Science Catalogue Service is a RESTful web service based on the principles defined in gCube Catalogue

Request

URL

The URL used to interact with the Science Catalogue Service is composed of two parts:

  • Base Service URL (e.g. https:/catalogue.d4science.org/science-catalogue)
  • Specific API (e.g. /organizations)

D4Science infrastructure uses cloud facilities allowing to replicate a service to achieve failover and load balancing.

Science Catalogue Service instances can be deployed and undeployed dynamically. For such a reason the Base Service URL MUST NOT be hard-cabled in the code because it can change over time.

To dynamically discover the Base Service URL you can use the Registry RESTful Service

You need to discover gCore Resource having:

  • class : DataCatalogue
  • name : science-catalogue

HTTP Headers

gCube Authorization Token

Any request performed to Science Catalogue MUST contains the gCube Authorization Token.

This is done using the HTTP Header gcube-token

gcube-token: YOUR-TOKEN

The gcube-token HTTP header acts as the standard Authorization HTTP header. Plese note that Authorization HTTP header cannot be used in place of gcube-token HTTP header.

Retrieve your gCube Authorization Token

the gCube Authorization Token is a UUID bound to yourself and a given Infrastructure context. To retrieve it, you just need to go to a VRE for which you are interested and use the Authorisation Options portlet (see below)

Authorisation option.png

Click on Show button and select the token.

Content Type

Any request must contain the indication of the interested content type.

For any operation returning a result, the client must specify the Accept HTTP Header.

Accept: application/json

For any operation sending content to the service, it is necessary to specify the Content-Type HTTP Header.

Content-Type: application/json

Actually, the service accepts and returns only JSON objects.

Except for a profile which can be also requested in XML.

HTTP Statuses

Any successful operation returns 200 OK status code except for create operation which return 201 Created or for the operations which do not provide any content and returns 204 No Content.

The most common error status a client can obtain are

A complete list of HTTP Status can be found here: https://httpstatuses.com/

You can report a 500 Internal Server Error the ticketing system. Please use this checklist before reporting an error:

  • replicate the request
  • the failure could be temporal due to network error, server issue so please retry the request after a certain amount of time
  • indicate how to replicate the error
  • indicate the time when the error occurred (this simplify the identification of the issue)

HTTP Methods

To be RESTful compliant Science Catalogue uses standard HTTP Methods to perform a listing of collections and CRUD (Create Read Update Delete) operations on instances.


Operation HTTP Method URL Success HTTP Status Safe Idempotent
Supported
HTTP Methods
OPTIONS /{COLLECTION} 204 No Content
(Supported HTTP Methods in Allow HTTP Header)
Y Y
List GET /{COLLECTION} 200 OK Y Y
Exists HEAD /{COLLECTION} 204 No Content Y Y
Create POST /{COLLECTION} 201 Created N N
Supported
HTTP Methods
OPTIONS /{COLLECTION}/{INSTANCE_ID} 204 No Content
(Supported HTTP Methods in Allow HTTP Header)
Y Y
Exist HEAD /{COLLECTION}/{INSTANCE_ID} 204 No Content Y Y
Read GET /{COLLECTION}/{INSTANCE_ID} 200 OK Y Y
Update PUT /{COLLECTION}/{INSTANCE_ID} 200 OK N Y
Patch PATCH /{COLLECTION}/{INSTANCE_ID} 200 OK N Y
Delete DELETE /{COLLECTION}/{INSTANCE_ID} 204 No Content N N
Purge PURGE /{COLLECTION}/{INSTANCE_ID} 204 No Content N N
Purge DELETE /{COLLECTION}/{INSTANCE_ID}?purge=true 204 No Content N N


About URL:

  • {COLLECTION} is the plural name of the entity type;
  • {INSTANCE_ID} is an identification which enables to univocally identify the instance in the collection.

About Safety and Idempotency properties:

  • A method is Safe if it does not produce any side effects. "This does not prevent an implementation from including behaviour that is potentially harmful, that is not entirely read-only, or that causes side effects while invoking a safe method" https://tools.ietf.org/html/rfc7231#section-4.2.1;
  • A method is Idempotent if the same operation repeated multiple times has the same side effect than using it one time. "repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ" https://tools.ietf.org/html/rfc7231#section-4.2.2.

Allamaraju[1] argues that DELETE idempotency should be accomplished client-side. The server should inform the client if a delete succeeded because the resource was really deleted or it was not found i.e., 404 Not Found error is suggested instead of 204 No Content. The latter situation should be treated as idempotent by the client. this service. For this reason, Science Catalogue does not provide idempotency for DELETE and PURGE operations.

You can find more information about this at https://restfulapi.net/http-methods/

Uncommon HTTP Methos

  • PATCH method allows to perform a differential update (i.e. an update which provide only the differences and not the whole new representation);
  • PURGE method is not a standard but is a widely used in service which requires this action (e.g. Varnish, Squid). The Science Catalogue provide support for this method but to support a wider range of clients it also provides the Purge action via DELETE with the additional get parameter
    purge=true

Collections

For each collection HEAD and OPTIONS operations are not shown in tables even there are always available.

Group Collection

Operation HTTP Method URL
List GET /groups
Create POST /groups
Read GET /groups/{NAME}
Update PUT /groups/{NAME}
Patch PATCH /groups/{NAME}
Delete DELETE /groups/{NAME}
Purge PURGE /groups/{NAME}
Purge DELETE /groups/{NAME}?purge=true

Only [Catalogue_Admin] are able to invoke non-safe methods.


Create (POST)

The content body of the request should be something like this

{

    "display_name": "Group Display Name",
    "type": "group",
    "title": "Group Title",
    "name": "group_name",
    "num_followers": 0,
    "state": "active"
}

The obtained result is something like this:

{
    "created": "2018-03-22T11:48:42.612063",
    "image_url": "",
    "approval_status": "approved",
    "description": "",
    "extras": [],
    "groups": [],
    "display_name": "Group Display Name",
    "is_organization": false,
    "type": "group",
    "title": "Group Title",
    "users": [
        {
            "email_hash": "f36a6a32b6d9a783ce27399873974e50",
            "created": "2016-06-15T14:05:27.208288",
            "openid": null,
            "about": "",
            "number_of_edits": 36327,
            "display_name": "gCube Service",
            "capacity": "admin",
            "number_created_packages": 0,
            "name": "gcubeservicerenamed",
            "activity_streams_email_notifications": false,
            "state": "active",
            "fullname": "gCube Service",
            "id": "89620d73-a828-4b68-83b8-b0a82a709120",
            "sysadmin": true
        }
    ],
    "tags": [],
    "package_count": 0,
    "image_display_url": "",
    "name": "group_name",
    "num_followers": 0,
    "state": "active",
    "id": "fd72502e-ddfa-4121-a12a-bb42e572d649",
    "revision_id": "0b5dda21-9bb0-4993-896b-d865e0d2f1f3"
}

Item Collection

Operation HTTP Method URL
List GET /items
Create POST /items
Read GET /items/{NAME}
Update PUT /items/{NAME}
Delete DELETE /items/{NAME}
Purge PURGE /items/{NAME}
Purge DELETE /items/{NAME}?purge=true

Resource Collection

Operation HTTP Method URL
List GET /items/{NAME}/resources
Create POST /items/{NAME}/resources
Read GET /items/{NAME}/resources/{ID}
Update PUT /items/{NAME}/resources/{ID}
Delete DELETE /items/{NAME}/resources/{ID}

License Collection

Operation HTTP Method URL
List GET /licenses

Organization Collection

Operation HTTP Method URL
List GET /organizations
Create POST /organizations
Read GET /organizations/{NAME}
Update PUT /organizations/{NAME}
Patch PATCH /organizations/{NAME}
Delete DELETE /organizations/{NAME}
Purge PURGE /organizations/{NAME}
Purge DELETE /organizations/{NAME}?purge=true

Only [Catalogue_Admin] are able to invoke non-safe methods.

User Collection

Operation HTTP Method URL
List GET /users
Create POST /users
Read GET /users/{NAME}
Update PUT /users/{NAME}
Delete DELETE /users/{NAME}

Only [Catalogue_Admin] are able to invoke non-safe methods.

Profile Collection

Operation HTTP Method URL
List GET /profiles
Read GET /profiles/{NAME}

A profile is defined using XML. It is possible to get the original XML definition using 'Accept' HTTP Header.

Accept : application/xml

instead of

Accept : application/json

Namespace Collection

Operation HTTP Method URL
List GET /namespaces
  1. Allamaraju S. RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity . O’Reilly. first ed. 2010