Response returned by Web service



The response returned by Web services is a JSON, generally in the following format:

{
    "status": "<status>",
    "data": "<returned data>"
}

Here is what each item returned corresponds:

---

 

status

string

Indicates the status of the request

Possible values: success or error

---

 

data

json

Returns the data of the request

 

---

Empty result

 

If there is no value for the request, the Web service will return the following JSON:

{
    "status" : "success",
    "data": null
}

Errors

 

The form the response will take depends on which version of the API you're using:

 

V1 - /api/<Web service>

The server will always respond with either an HTTP Status Code "200" or "500", and you'll have to rely on the status and message properties of the response body to identify genuine errors.

Very important This version is marked as deprecated. It is preferable to use V2 for all new developments or updates to existing integrations.

 

V2 - /api-v2/<web service>

The server will respond with HTTP Status Code "200" only if no error has occurred. If necessary, an appropriate Status Code will be used depending on the nature of the error.

---

 

Error: Header Content Type

If you don't use application/json in the Content Type header, you'll get the following response:

 

In V2

HTTP Status Code: 422

{
    "message": "The given data was invalid.",
    "errors": {
        "actionParameters": [
            "Action parameters are required"
        ]
    }
}

In V1

HTTP Status Code: 500

{
    "status": "error",
    "data": null,
    "message": "Les paramètres passés à la procédure sont incomplets."
}

---

Error: Header Accept

If you don't use application/json in the Accept header, you'll get the following response:

 

En V2

HTTP Status Code: 406 Since this header is missing, the server responds with the complete error page (HTML)

 

En V1

HTTP Status Code: 200

{
    "status": "error",
    "message": "Wrong content type in Accept header
}

---

Error: Headers prim-username et prim-userkey

If identification fields are missing from the header, you'll get the following response:

 

In V2

HTTP Status Code: 403

{
    "status": "error",
    "message": "Authentication parameters missing or malformed."
}

In V1

HTTP Status Code: 200

{
    "status": "error",
    "message": "Authentication parameters missing or malformed."
}

---

Error: Login info. and/or access rights

If you call a web service and the login information is incorrect, or if you haven't enabled access rights to a web service in PRIM, you'll get the following response:

 

Example with the web service newJobCount:

 

In V1 and V2

HTTP Status Code: 500

{
  "status": "error",
  "data": null,
  "message": "Acces denied::newJobCount:<My username>:<Web service ID>:<Web service name>:<My IP address>:<My key>:[{\"ParamName\":\"JobType\",\"ParamValue\":\"B\"},{\"ParamName\":\"JobFilled\",\"ParamValue\":\"N\"}]"
}

---

Error: Web service does not exist

If you call a web service (action) that does not exist, you will receive the following response:

 

In V1 and V2

HTTP Status Code: 500

{
    "status": "error",
    "data": null,
    "message": "Web service call. Wrong action call: <name of web service>"
}

---

Error: Expected properties

If an error occurs in the names of the JSON fields passed by the request, or if you pass a field that doesn't exist for a web service, you'll get the following response:

 

In V1 and V2

HTTP Status Code: 500

{
    "status": "error",
    "data": null,
    "message": "Les paramètres passés à la procédure sont incomplets."
}

---

Error: JSON invalide

If the JSON sent to the web service is malformed, you'll get the following response:

 

In V2

HTTP Status Code: 422

{
    "message": "The given data was invalid.",
    "errors": {
        "actionParameters": [
            "Action parameters are required"
        ]
    }
}

 

In V1

HTTP Status Code: 500

{
    "status": "error",
    "data": null,
    "message": "Les paramètres passés à la procédure sont incomplets."
}