Open Documentation Menu

General information about API functions (DMSApp)

In this chapter, you can find all the topics that apply to all types of use of the API functions in DMSApp.

Determining a repository

Released: JSON representation

To implement your own functions, you always need the ID of the repository. With DMSApp, you have the option of accessing different repositories if you have configured multiple repositories in your company or organization.

If, for example, you want to start a search, you must first select a repository. To specify the repository, execute a HTTP GET request for the REST resource /dms.

The repository ID is determined in two steps:

  • Determining the link relation for retrieving the list of repositories

  • Retrieving the list of repositories

Determining the link relation for retrieving the list of repositories

The URL for a repository is available as a link relation in the response to the HTTP GET request.

Request

GET /dms
Accept: application/hal+json

Response

{
        _links: {
                repo: {
                        href: "/dms/r/{repositoryid}",
                        templated: true
                }
        }
}

Retrieving the list of repositories

To call repository-specific functions, you require the repository ID.

Replace the {repositoryid} placeholder in the URL "/dms/r/{repositoryid}" with the repository ID. If you do not know the repository ID, open the URL /dms/r as follows:

Request

GET /dms/r
Accept: application/hal+json

In the response, you receive an array of repositories in which the repository ID is listed as the id property and the repository's display name is listed as the name property.

Response

{
        repositories: [
                {
                        id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27",
                        name: "Contoso (A)"
                },
                ...
        ]
}

If you already know the repository ID, then you can replace the {repositoryid} placeholder in the URL /dms/r/{repositoryid} with the repository ID. When you open the URL with the repository ID, you receive the following result:

Request

GET /dms/r/dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27
Accept: application/hal+json

The JSON object in the response is the same object as the object in the list of JSON objects from the request for the URL /dms/r.

Response

{
        id: "dee1f3d3-eae8-5d9d-84d8-2d758c5ddc27",
        name: "Contoso (A)"
}
Overview of formats for errors

Released: JSON representation

In this chapter, you will learn more about the basics of error handling and the format in which errors are returned.

Depending on the result of the processing of an HTTP request, the request is answered with different HTTP status codes. Descriptive information can be returned as JSON as an option.

Example for a response upon a failed request:

Response

HTTP/1.1 400 BadRequest
  
{
    "reason": "10019: Missing value for a mandatory property.",
    "severity": 1,
}

Description of parameters for response upon a failed request:

Property

Description

reason

An optional short description of why the error has occurred. This text is used as the error message’s title.

hint

An optional message for the user containing troubleshooting tips.

details

Optional detailed information about the error.

severity

Optional error severity. Possible values are:

Success = 0,
Information = 1,
Warning = 2,
Error = 3