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

Use	HTTP method	Example	Description
Request a list of resources	GET	GET /resources	Returns a list of resource objects
Search through a list of resources	GET	GET /resources?attribute=xxxx	Returns a list of resource objects filtered on the xxxx attribute
Request a resource	GET	GET /resources/1234	Returns a resource object identified by ID 123
Create a resource	POST	POST /resources/1234	Creates a resource object using the JSON attributes specified in the request body
Fully update a resource	PUT	PUT /resources/1234	Completely updates the resource object identified by ID 1234 with the JSON attributes specified in the request body
Partially update a resource	PATCH	PATCH /resources/1234	Partially updates an object with the content of the request body
Delete a resource	DELETE	DELETE /resources	Deletes the resource object identified by ID 1234

For more information about the standard RESTful implementation:

HTTP Methods - REST API TutorialREST API Tutorial

HTTP return code and response body

Code	Description	Reponse body
200	Request successfully processed	Varies depending on what was
201	Successfully created object	Object created
202	Order of creation of the object successfully processed, the request will be processed asynchronously	Empty or tracking object describing the processing of the asynchronous request
400	Bad query - Syntax or consistency error in the query. Must be corrected by the issuer	VBlank or indication of the error to be corrected on the client side
401	Unauthenticated access to the resource	Vacuum
403	Unauthorized access	Vacuum
404	Non-existent resource	Vacuum
409	Conflict	Vacuum
422	Inconsistent data	Vacuum
500	Fatal API error	Vacuum
503	Service temporarily unavailable	Vacuum

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")))