Exporting and importing repository configuration via REST
This page explains how to execute Document.One (D1) REST API calls allowing you to export and import repositories.
General
D1 provides REST API services allowing you to export and import repository configuration. All export services allow you to export all repositories, but you can also retrieve configuration by any of the following categories:
- Repository ID (
/export/configuration/
endpoint) - Repository name (
/export/configuration/by-names
endpoint) - Repository technical name (
/export/configuration/by-technical-names
endpoint)
Import is always done through the /import/configuration
endpoint. Check Endpoints for detailed information on what each endpoint can do.
You can get all of the export parameters in the Administration Area in the user interface. Name and technical name are visible in the preview:
The ID is visible in the detailed view of the repository (select Details to open):
Repository migration between hosts
cURL example
The example below shows a typical workflow consisting of four cURL requests, where you export a configuration from one host and import it into another one.
Adapt the following parts of the below requests:
https://[HOST]:[PORT]
— Adjust the protocol (http
orhttps
) and host name.[USER_NAME]
— Replace with your user name.[PASSWORD]
— Replace with your password.repositoryNames
— Replace with real repository names, as in-F repositoryNames=["Real name 1","Real name 2"]
.@/path/to/myrepo-export.zip
— Replace with the actual path (for example,@/mnt/c/Downloads/myrepo-export.zip
).
- Open a session to the D1 host.
ADX_DEV_SESSION_ID=$(curl --silent --location --insecure --request POST 'https://[HOST]:[PORT]/tribefire-services/api/v1/authenticate?user=[USER_NAME]&password=[PASSWORD]' --header 'Content-Type: application/json' | cut -d '"' -f 2)
- Export the repository from D1-dev to myrepo-export.zip.
curl --insecure --request GET "https:///[HOST]:[PORT]/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-names?sessionId=${ADX_DEV_SESSION_ID}" --header "accept: application/json" -F repositoryNames="[Real name 1,Real name 2]" --output /path/to/myrepo-export.zip
- Open a session to the D1 host. (Ignore this step, if you are calling the same D1 instance.)
ADX_TEST_SESSION_ID=$(curl --silent --location --insecure --request POST 'https://[host]:[port]/tribefire-services/api/v1/authenticate?user=admin&password=password' --header 'Content-Type: application/json' | cut -d '"' -f 2)
- Import the repository from myrepo-export.zip to D1.
curl --insecure --request POST "https://[host]:[port]/tribefire-services/api/v1/access.adx.admin/v1/import/configuration?sessionId=${ADX_TEST_SESSION_ID}" --header "accept: application/json" --header "Content-Type: multipart/form-data" --form "autoSync=true" --form "importRepositoryOption=full" --form "importUsersOption=none" --form "useRuntimeValues=false" --form "resource=@/path/to/myrepo-export.zip;type=application/zip"
The video below shows how to send adopted cURL requests to D1:
Note that some of the UI components shown in this video might have changed as the video was created based on an older version of the D1.
Endpoints
You can use three different endpoints to export repositories (by ID, by name or by technical name). Importing is always done via the import/configuration
endpoint. Export query parameters are optional — if you do not enter them, all repositories will be exported. Check Parameters below for information on request parameters and their values.
You need to authenticate before using any of the below endpoints — the session ID must be passed as a query parameter.
HTTP request | Endpoint | Service description | Request query parameters | Form data | Returns |
---|---|---|---|---|---|
GET | https://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/ | Export repository configuration by IDs | sessionId, repositoryIds (array) | none | .zip file with repository configuration. |
GET | https://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-names | Export repository configuration by names | sessionId, repositoryNames (array) | none | .zip file with repository configuration. |
GET | https://host:port/tribefire-services/api/v1/access.adx.admin/v1/export/configuration/by-technical-names | Export repository configuration by technical name | repositoryTechnicalNames (array) | none | .zip file with repository configuration. |
POST | https://host:port/tribefire-services/api/v1/access.adx.admin/v1/import/configuration | Import repository configuration | none | autoSync, importRepositoryOption, importUsersOption, resource, useRuntimeValues |
Parameters
The following table lists the parameters and their descriptions:
Name | Data type | Description |
---|---|---|
sessionId | string | The session ID returned when you authenticate. |
repositoryIds | array | Array of one or more repository IDs, for example ["ab-cd-1234", "ef-gh-5678"] . |
repositoryNames | array | Array of one or more repository names, for example ["Repository name 1", "Repository name 2"] . |
repositoryTechnicalNames | array | Array of one or more repository technical names, for example ["Technical name 1", "Technical name 2"] . |
autoSync | boolean | Indicates whether affected repositories should be automatically synchronized after import. |
importRepositoryOption | string | Specifies option for repository import. delta — import only missing configuration, full — do a full import, none — do not import repository configuration (in case you only want to import users). |
importUsers | boolean | Indicates whether users/roles/groups should be imported. |
resource | string | The file system path to the previously exported .zip archive with repository configuration to be imported. |
useRuntimeValues | boolean | Indicates whether environment specific runtime values should be used instead of the values from the export package. |
Try It Out in OpenAPI
All of the above endpoints are documented and exposed in our OpenAPI pages, where you can try them out.
Log in to Document.One (D1). Open the Administration API from the landing page:
A list of repository endpoints is exposed. Switch to Swagger 2.0 in case of any issues with the default page:
Find the Export/Import section (on the top of the page):
Expand and try out the endpoints yourself, following the guidelines provided in OpenAPI.
Exporting via D1 user interface
You can execute the services described above via the D1 Administration user interface.
See Exporting and importing repository configuration via D1 user interface for more information.
OpenAPI
For code samples, see