Skip to main content

Retrieve master data

Learn how to retrieve data from the Proactis APIs

To retrieve master data from Proactis most APIs have two distinct endpoints that serve different purposes: one for fetching a list of results based on filters or pagination, and another for retrieving individual results.

List results endpoint​

This endpoint is a fundamental part of the Proactis APIs and allows clients to request a list of results based on specific criteria, such as filters and pagination. This endpoint is particularly useful when dealing with large datasets, where returning all results at once would be impractical or inefficient.

  1. Endpoint URL

    The URL is where the client sends its request to fetch a list of results. This URL is designed to be unique and specific to this functionality, and it might look something like /accounting/v1/{domainId}/costdimensions/CostCenter/values.

  2. HTTP method

    A GET request is used to interact with this endpoint. This indicates that the client is requesting data from the server.

  3. HTTP headers

    Proactis APIs require authentication. For this each request requires two HTTP-headers (Authorization and x-api-key) to be added.

    Some APIs also allow the client to indicate the type of response (XML or JSON). This is done by adding the Accept header. The specific API documentation will let you know whether this is supported.

  4. Query parameters

    Clients can include query parameters in the URL to customize the data they want to retrieve. Some common query parameters used with this endpoint are:

    • pageNumber: This parameter indicates which page of results the client wants to retrieve. Pages are used to break up the data into manageable chunks, preventing the need to retrieve the entire dataset at once.
    • pageSize: This parameter specifies the number of results to be included in each page. It works in conjunction with the pageNumber parameter to determine how many results are shown per request.
    • Additional parameters: Depending on the API's design, there might be other parameters for sorting the results or filtering.

  5. Response

    After processing the client's request, the API responds with a XML or JSON array that contains the list of results that match the specified criteria. The response may also include metadata to assist with pagination and result count information.

    In the example below, the results array contains the list of results for the requested page, and the totalElements field indicates the total number of results available. The pageNumber and pageSize fields provide pagination information.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <page>
       <pageNumber>0</pageNumber>
       <pageSize>2</pageSize>
       <totalElements>82</totalElements>
       <content>
          <costCenter>
             <id>CC-001</id>
             <online>true</online>
             <erpId>HR-654</erpId>
             <departments/>
             <lastModified>2023-08-17T14:16:17+02:00</lastModified>
          </costCenter>
          <costCenter>
             <id>CA-002</id>
             <online>true</online>
             <departments/>
             <lastModified>2023-07-27T08:07:34+02:00</lastModified>
          </costCenter>
       </content>
    </page>

Individual result endpoint​

This endpoint in a RESTful API is used to retrieve detailed information about a single result or item. The endpoint is particularly useful when a client already knows the unique identifier of the item they want to retrieve and need more specific details about it. Here's a more in-depth explanation of how this endpoint works:

  1. Endpoint URL

    The URL is constructed in a way that includes the unique identifier of the item to be retrieved. The URL might look something like /accounting/v1/{domainId}/costdimensions/CostCenter/values/{costCenterId}, where {costCenterId} is the actual identifier of the result you want to retrieve.

  2. HTTP Method

    Just like with the "List results endpoint", a GET request is used to interact with this endpoint. This signals to the server that the client is requesting information about a specific item.

  3. HTTP headers

    Proactis APIs require authentication. For this each request requires two HTTP-headers (Authorization and x-api-key) to be added.

    Some APIs also allow the client to indicate the type of response (XML or JSON). This is done by adding the Accept header. The specific API documentation will let you know whether this is supported.

  4. Response

    After processing the request, the API responds with a XML or JSON object that contains detailed information about the requested item. This information might include various attributes, properties, and any related data associated with the item. In this example, the object contains detailed information about the specific cost center with an ID of CC-001.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <costCenter>
       <id>CC-001</id>
       <name>Human Resources</name>
       <online>true</online>
       <erpId>HR-654</erpId>
       <departments>
          <department>A-6000</department>
          <department>A-1000</department>
       </departments>
       <lastModified>2023-08-17T14:16:17+02:00</lastModified>
    </costCenter>

  5. Error Handling

    It's important to consider error handling when working with this endpoint. If the client requests an item that doesn't exist or provides an invalid identifier, the API responds with an appropriate error message, typically using appropriate HTTP status codes (e.g., 404 Not Found for a non-existent item).

Contents