ITCare API

Getting started with the ITCare API

The ITCare REST API complies with the OpenAPI standard specifications. The online documentation is available at this address: https://api.cegedim.cloud/

Example:

Get ITCare status
curl -X GET "https://api.cegedim.cloud/itcare/health"

How do I authenticate to the ITCare API ?

The ITCare API uses the OAuth 2.0 protocol for authentication and authorization. It supports the usual OAuth 2.0 scenarios such as those used for web servers and client applications.

This means that each API request must contain an "Authorization" header embedding an access token previously obtained through credentials.

curl -X GET "https://itcare.cegedim.cloud/itcare/{api-definition}/{api-endpoint}" -H "Authorization: Bearer {token}"

How do I get an API account?

To query the ITCare API, an API account is required in order to obtain the mandatory access token. To obtain this API account, a request must be submitted to the cegedim.cloud support teams by providing the following information:

  • The target organization

  • A simple description of the target usage of the API

How do I get an access token?

To obtain an access token, the client must submit a request to the endpoint /token. The authorization server requires client authentication to issue an access_token. Here is an example of an access_token request:


curl -X POST "https://accounts.cegedim.cloud/auth/realms/cloud/protocol/openid-connect/token" \
-H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"

In general, we can use the base64 command to encode a string. Using command-line tools in Linux for exemple :

$echo -n 'CLIENT_ID:CLIENT_SECRET' | base64
(gives the base64 of your CLIENT_ID:CLIENT_SECRET)

If the access_token request is allowed and valid, here is a sample response:

{
   "access_token":"...",
   "expires_in":1200,
   "refresh_expires_in":7200,
   "refresh_token":"...",
   "token_type":"bearer"
}

When the token expires, it is possible to :

  • Request a new access_token

  • Refresh the token by querying the endpoint /token

curl -X POST "https://accounts.cegedim.cloud/auth/realms/cloud/protocol/openid-connect/token" \
-H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&refresh_token=****************"

What are the REST conventions of the ITCare API?

The ITCare API uses the JSON format for both input and output messages (payload). This also includes the bodies of HTTP messages of type PUT, PATCH, POST and DELETE. It therefore respects the standards of a REST API in terms of HTTP verb and HTTP return code.

HTTP methods and URI content type

For more information about the standard RESTful implementation:

HTTP return code and response body

What date/time format is used by the API?

JSON does not natively support the Date/Time format. All parameters tagged as Date by the API are therefore strings in ISO8601 format.

YYYY-MM-DDTHH:MM:SS.sssZ

Z corresponds to the time zone: +0200 for example.

2016-06-01T12:27:19.000+0200

For GET requests, do not forget to URL-Encode these parameters.

Can I run blank actions via the API?

Some methods allow testing of API calls without actually triggering the action in ITCare. However, the validation is still done. To activate the Dry Run mode, simply add a custom header to your HTTP requests:

ITCare-DryRun: true

Once the server processes your request, the same custom header will be included in the response.

How do asynchronous actions work?

Some methods are asynchronous and require a delay after their invocation. This applies to time-consuming transactions such as resource administration or reporting. Methods that operate asynchronously will respond:

  • an HTTP return code 202

  • a body containing a tracking ID for the current asynchronous operation

Here is an example of code in Python that explains the asynchronous operation:

"""
Launch action and get its descriptor
"""
action = itcare.post('/api/resource', payload=my_payload)
  
"""
Loop on getting its status
"""
while action['status']=='IN_PROGRESS':
    time.sleep(1)
    action = itcare.get('/api/actions/{}'.format(action['id']))
  
"""
Print its status
"""
print action['status']

The status of the actions can be :

  • IN_PROGRESS

  • SUCCESS

  • ERROR

How to get started quickly with Python ?

Requirements:

  • Python3

  • pip (to install the SDK)

Run the following commands to install the ITCare Python SDK.

pip install --ignore-installed --upgrade --trusted-host itartifacts.cegedim.cloud --index-url https://itartifacts.cegedim.cloud/artifactory/api/pypi/pypi/simple itcare
pip install --ignore-installed --upgrade --trusted-host itartifacts.cegedim.cloud --index-url https://itartifacts.cegedim.cloud/artifactory/api/pypi/pypi/simple pyoidcclient

Create your first script

# lib import
from itcare import ITCareService
  
# API Account on ITCare
ITCARE_USERNAME="my-client-id"
ITCARE_PASSWORD="my-client-password"
  
# Create API client
itcare = ITCareService(url="https://api.cegedim.cloud/itcare/compute", oidc_provider="https://accounts.cegedim.cloud/auth/realms/cloud", oidc_client_id=ITCARE_USERNAME, oidc_client_secret=ITCARE_PASSWORD)
  
# get instances
instances = itcare.get('/instances')
  
for instance in instances:
  print("Instance {}".format(instance.get("name")))

Last updated