SData web service for Details

This article describes how to read the details of a single resource with the Web API.

Read URL

You can read a single resource by sending an HTTP GET request to the following URL:

http://myserver:myport/api1/x3/erp/MYENDPOINT/MYCLASS('MYKEY')?representation=MYREPR.$details

where:
  • myserver:myport is your server name and port number. For example localhost:8124 if the SAFE X3 web server is installed locally.
  • MYENDPOINT is the name of your Sage X3 endpoint.
  • MYCLASS is the name of the class that you want to query. It may be a standard class like BPCUSTOMER or a custom class that you have implemented (see the class dictionaries documentation).
  • MYKEY is the value of the primary key of the resource. If the key is composite, the components are separated by a tilde (~).
  • MYREPR is the name of the representation that you want to query. It may be a standard representation like BPCUSTOMER or a custom one (see the representation dictionaries documentation).

Note MYREPR must be a representation for MYCLASS. Otherwise you will get an error. A future version of the Web API will allow you to pass only MYREPR but this version (api1) requires both parameters.

Status code

If successful, the request will return an HTTP status of 200.

Otherwise it will return an HTTP error status (4xx or 5xx).

JSON result

A Web API read request returns a JSON object structured as follows:

CODECODE CODE javascript
{
    "$uuid": "6bc5644d-df51-4dcf-93ef-c388dab85ff8",
    "$etag": "2015-08-18T08:14:25Z",
    "BPCNUM": "0113",
    "BPCNAM": "ACME Inc.",
    ...
}

Note: the actual payload may have more $... properties. These properties are internal and should be ignored.

If the resource has child resources they will be directly embedded into the payload as an array. For example, a document with lines will have a payload like:

CODECODE CODE javascript
{
    "$uuid": "fd5b4b40-f1b4-467e-95ff-dd19f1a95cd7",
    "$etag": "2015-08-18T08:14:25Z",
    "SOHNUM": "S004",
    ...
    "SOHSOP": [{
        "$uuid": "1df2a3f1-21c9-4547-9b9e-27f1c840252e",
        "ITMREF": "ITM003",
        ...
    }, {
        "$uuid": "c9e6442c-76cf-4dce-a740-288b5542e479",
        "ITMREF": "ITM032",
        ...
    }, {
        ...
    }],
    ...
}

The $uuid values are important if you need to update the resource. The are used to match your updated lines with existing lines.

If the resource has references to other resources, each reference will be returned as two fields: a field which holds the primary key of the referenced resource (several fields if the key is composite), and a field with an _REF suffix which contains a small object with additional information about the referenced resource. Here is a typical example:

CODECODE CODE javascript
{
    "$uuid": "fd5b4b40-f1b4-467e-95ff-dd19f1a95cd7",
    "$etag": "2015-08-18T08:14:25Z",
    "SOHNUM": "S004",
    ...
    "CUR": "EUR",
    "CUR_REF": {
        "$title": "EURO",
        "$symbol": "EURO",
        ...
    },
    ...
}

Having a status equal to 200 does not mean that the record exists. You have to check the JSON feed returned, that might be one of the following:

Successful return

The body contains the data like this example (some technical properties are not reproduced here):
{
  "$uuid": "90ceba58-9be4-8649-8278-1321b622a449",
  "$etag": "2015-12-21T17:13:18Z",
...
  "BPCNUM": "AO001",
  "BPCNUM_REF": {
    "$title": "Luanda BTT",
    "$description": "Luanda BTT"
  },
  "COMMENT": "Customer Luanda BTT lead #1",
  "LEADDATE": "2015-12-09",
  "LEADNUM": 1
}

Unsuccessful return

The body contains an error payload like this example :
{
  "$diagnoses": [
    {
      "$severity": "error",
      "$message": "721 : Record does not exist"
    }
  ]
}

Testing interactively

As described in the overview, you can test Web API queries directly in the browser, or in a tool like Postman.