References

Swagger

The Udianas API has a Swagger UI accessible through the URL api.udianas.net/swagger. The methods are detailed with the different response codes and parameters. The Swagger documentation is calculated compared to existing methods, so it gives better accuracy. The definition of the objects used in the Udianas API is detailed in Swagger. In the standard Swagger interface, an input area called api key is available. It is not used by the Udianas API.

Entry point

To access API version 1, the entry point is as follows:

http://api.udianas.net/v1

The entry point contains the version number. The sub-versions (1.1, 1.2, etc.) will remain compatible with version 1.0 The following versions (2, 3, etc.) will have a specific entry point. 

Error codes

The following error codes are returned by responses:

• 200 Everything went as planned.
• 404 Item not found: usually when the identifier does not match an existing record.
• 403 Access denied: the method does not exist or the access key is incorrect.
• 401 Not allowed: parameters do not match. Example: To have the information of a tree, it is necessary to know the id of the deceased person; the error occurs if the person's id does not match.
• 5xx Unexpected problem on the Udianas server

Images

Images are passed by reference via their URL.

Identification of the operator

Identification of the calling website is required for security reasons. It is coupled with an internal test in the API to detect the origin of the request.

Test or live mode is also included in the key.

Example:

• The test key: tex_test_123456789
• The production key: ex_live_123456789

The key is the first element in the query string. This way, the root of all queries is the same:

http://api.udianas.net/V1/ex_live_123456789

If the identification is incorrect, the response of the method returns the error code 403.

The notion of context

Each sale is made in a specific context. The general context is that of the website. Sub-contexts are also present. The press headline related to the deceased is a sub-context, the undertaker is another. Defining the context of each transaction allows this context to be attached to the souvenir trees concerned and to use these elements for post-sale operations. All API responses contain a Context element, here is an example:

  "Contexte": {
    "Environnement": "test",
    "ContexteGeneral": "Gif",
    "ContexteGeneralId": 3,
    "Contexte": "Contexte global",
    "ContexteId": 1,
    "ContexteGroupeEpfId": 0,
    "ContexteEpfId": 0,
    "ContexteEpfAgenceId": 0,
    "ContexteGroupePresseId": 0,
    "ContexteTitreId": 0,
    "ContexteTitreEditionId": null,
    "ContexteAssuranceId": 0,
    "ContexteMaisonReposId": 0
  },

Where the elements are:

• Environnement Test or live environment
• ContexteGeneral Operator’s name
• ContexteGeneralId General context’s id
• Contexte Operator selection context
• ContexteId Operator selection context’s id
• ContexteGroupeEpfId Funeral director group identifier
• ContexteEpfId Identifier of a funeral home
• ContexteEpfAgenceId Identifier of a funeral home’s agency
• GroupeTitrePresseId Press group identifier
• ContexteTitreId Press title identifier
• ContexteTitreEditionId Press title’s edition identifier
• ContexteAssuranceId Insurance company identifier
• ContexteMaisonReposId Rest Home group identifier

The udianas and the trees contain all of these identifiers.

In the example, the Contexte object is sometimes eluded to make it easier to read the object in which it is included.

More details on contexts' page

 

Test mode

A test mode is integrated to carry out tests. A test database is implemented.

In the test mode, operations are performed on the test database.

In test mode, if a list of trees or transactions is requested and the response contains no records, a test record is returned. The error element contains a particular message and the TotalNumber of the response remains at 0.

This allows for example to test on the contexts even if nothing exists yet.

The Environment element of the response context contains the mode:

Test Mode :

  "Contexte": {
    "Environnement": "test",
    "ContexteGeneral": "OperatorName",
    "ContexteGeneralId": 99,
    ...
  }

Production mode:

  "Contexte": {
    "Environnement": "production",
    "ContexteGeneral": "OperatorName",
    "ContexteGeneralId": 99,
    ...
  }

The type of key used defines the test or production mode.

• Test key format xx_test_a1a1a1a1a1a1a
• Production key format xx_live_a1a1a1a1a1a1a

Lists

Some API methods return lists of items: the list of species, the list of a person's trees, etc. A paging system is integrated.

More details about lists on [Lists' page][2]

[2] /DocApi/Lists

Json format responses

The API method response is a JSon format string consisting of a series of general parameters (type of object, status, generation time, etc.) and the requested data.

Example:

{
  "Id": 0, 
  "Objet": "type_d_objet",
  "Date": "2017-12-6T15:11:35Z",
  "Statut": "succès",
  ...
}

• Object type of object returned
• Id object identifier (empty if the object is a list)

Managed errors

Errors handled by the API are accompanied by a specific Json object:

{
  "Objet": "Espèce",
  "Statut": "Erreur",
  "Message": "Accès refusé",
  "Contexte": {
    ...
  },
  "HttpStatusCode": 403
}

The name of the object is that of the expected object in the event of a positive response, but the status is Error, the message gives a description of the error and the context is passed on to additional information.

The http status code completes the response.