Skip to content

Using Project Access Token

In this guide, we'll explore how to interact with DATAMIMIC projects programmatically using project access tokens. This approach allows you to manage your projects and generate data through API calls, which is particularly useful for automation and CI/CD pipelines.

Prerequisites

  • Take a look at the DATAMIMIC External API Reference or access your datamimic instance external_api_docs to understand the API endpoints and how to use them
  • A DATAMIMIC project
  • curl installed on your system
  • jq (Optional) installed on your system (for JSON artifact processing)

Getting Started

  1. Clone the Demo Basic JSON from the DATAMIMIC Demo Store.
  2. Add a new project access token for this newly clone demo project.
  3. Note down both the Project ID and the newly Project Access Token.

Basic Operations

Reading Project Files Metadata

To get all your project's files metadata information:

1
2
3
4
curl -X 'GET' \
  'https://your-datamimic-instance/api/v1/{project-id}/files' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-project-access-token}'

Reading a Project File Content

To get a project file content:

1
2
3
4
curl -X 'GET' \
  'https://your-datamimic-instance/api/v1/{project-id}/files/{file-name}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-project-access-token}'

Creating a Project File

To create a new project file, you can use the curl command with the -F flag to upload the contents of a local file directly, instead of specifying the file content inline.

Note

New file can only be created if it not already exists in the project. Otherwise, you need to update the existing file.

1
2
3
4
5
6
curl -X 'POST' \
  'https://your-datamimic-instance/api/v1/{project-id}/files' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-project-access-token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<local-file-path>;type=text/xml'

Updating Project Files

Make any change you want to the file content locally then update it to the system.

Note

A file can only be updated if it already exists in the project. If it doesn't exist, you need to create it first.

To update a file's content:

1
2
3
4
5
6
curl -X 'PUT' \
  'https://your-datamimic-instance/api/v1/{project-id}/files/{file-name}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-project-access-token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@<local-file-path>;type=text/xml'

Deleting a Project File

To delete a project file:

1
2
3
4
curl -X 'DELETE' \
  'https://your-datamimic-instance/api/v1/{project-id}/files/{file-name}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-project-access-token}'

Generating Data

To trigger data generation:

1
2
3
4
5
curl -X 'POST' \
  'https://your-datamimic-instance/api/v1/{project-id}/generate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-access-token}' \
  -d '{"task_type": "standard"}'

This call will return a Task ID that you can use to track the generation progress and download artifacts.

Downloading Generated Data

To download and view generated artifacts:

1
2
3
4
curl -X 'GET' \
  -H 'Authorization: Bearer {your-project-access-token}' \
  'https://your-datamimic-instance/api/v1/{project-id}/task/{task-id}/artifact/download/{artifact-file-name}' \
  -o person.json && jq . person.json

or you can also download all the artifacts created by the task as a single zip file:

1
2
3
4
curl -X 'GET' \
  -H 'Authorization: Bearer {your-project-access-token}' \
  'https://your-datamimic-instance/api/v1/{project-id}/task/{task-id}/artifact/download' \
  -o artifacts.zip

Example Workflow

Here's a complete example of a typical workflow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# Set your variables
PROJECT_ID="your-project-id"
ACCESS_TOKEN="your-access-token"
API_BASE="https://your-datamimic-instance/api/v1"

# Read current configuration
curl -X 'GET' \
  "${API_BASE}/${PROJECT_ID}/files" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'accept: application/json'

# Make changes to datamimic.xml as needed

# Update configuration
curl -X 'PUT' \
  "${API_BASE}/${PROJECT_ID}/files/datamimic.xml" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'Content-Type: multipart/form-data' \
  -F '[email protected];type=text/xml'


# Generate data
TASK_ID=$(curl -X 'POST' \
  "${API_BASE}/${PROJECT_ID}/generate" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"task_type": "standard"}'

# Check infomation about the task
curl ${API_BASE}/${PROJECT_ID}/task/${TASK_ID}" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

# From the task_id you can also download all the artifacts created by the task as a single zip file

curl ${API_BASE}/${PROJECT_ID}/task/${TASK_ID}/artifact/download \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
  -J -O 

Note

Replace your-datamimic-instance, {project-id}, {task-id} and {your-access-token} with your actual values in all examples.

Tips

You can visit the external_api_docs to see the API endpoints, these endpoints contains clear examples and documentation using our Swagger UI for you to try out the API endpoints.

Using the Swagger UI, you can also see the curl command to use the API endpoints. This can make the API calls easier to understand and use.

Recap

In this guide, we explored how to programmatically interact with DATAMIMIC projects using project access tokens. Here's a summary of the key concepts and operations:

  1. Setup and Authentication:

    • Created/used a DATAMIMIC project
    • Generated a project access token
    • Used the token for API authentication
  2. Basic Operations:

    • Reading project files using GET requests
    • Updating file content using POST requests
    • Triggering data generation
    • Downloading and viewing generated artifacts
  3. Workflow Integration:

    • Learned how to combine operations into a complete workflow
    • Used environment variables for configuration
    • Implemented basic automation patterns

These API operations enable you to automate DATAMIMIC project management and integrate it into your development workflows, CI/CD pipelines, or custom applications.