Skip to main content

Getting Started

Updated

 

This article that will guide you through the process of generating API tokens, along with some examples of common API commands that you can run against MedStack Control. The steps outlined in this article will help you create an API token that will enable you to access your account and perform various actions through the API. Additionally, we will provide examples of frequently used API commands that you can use to Deploy and Manage services on MedStack Control

Generate API Tokens on MedStack Control

Here is a step-by-step guide on how to generate an API token:

  1. Log into MedStack Control 
  2. Click on your name on the top right corner of the navigation bar and select API Tokens.
  3. Click on the "New Token" button to create a new API token.
  4. Select the company that the token will be authorized to make API requests within. The company selected will determine the scope of the token.
  5. Optionally, add a note to help you remember the purpose of the token.
  6. Click the "Generate token" button.
  7. Copy and the store the newly generated personal access token value as it will not be visible again.

And that's it! You have successfully generated an API token for your account. Remember to keep your token secure and confidential, as it allows access to your account and potentially sensitive data.

 

API Authentication using the API Tokens

Personal access tokens are used for basic authentication in API requests where the username is the token key, and the password is the token value. These credentials are passed in the header of an API request to the MedStack Control API.

curl -u username:password https://api.example.com

Note: Replace "username" and "password" with API token key and token value.

Get Company ID

Here's example of how you can use the token key and value to authenticate and run an API command to get your Company ID. 

curl -u JBO5z2Ex78p6LmlKV6GyrnwD:HMySkImRY7I0oKX0TWBHWhjSiC9mRQnf \
  --request GET --url https://api.medstack.co/v1/companies/current

The purpose of this request is to retrieve details about the currently authenticated company.

 

Output:

{
"id":"company_YA",
"object":"company",
"name":"MedStack Internal",
"street_address":"600-10 Dundas St E",
"city":"Toronto",
"province":"Ontario",
"country":"Canada",
"postal_code":"M5B 2G9",
"phone_number":"+1.647.400.7268"
}

Get Cluster ID

Here's example of how you can use the token key and value to authenticate and run an API command to get a list of all the cluster and Cluster IDs for your Company. 

curl -u JBO5z2Ex78p6LmlKV6GyrnwD:HMySkImRY7I0oKX0TWBHWhjSiC9mRQnf --request GET \
  --url https://api.medstack.co/v1/companies/company_YA/clusters \
  --header 'accept: application/json'

The purpose of this request is to retrieve a list of clusters associated with the specified company.

Output:

{
"object":"list",
"data":[
{
"id":"cluster_o9ZkRD3R",
"object":"cluster",
"label":"ndlc-prod"
},
{
"id":"cluster_LB3DGPQx",
"object":"cluster",
"label":"JB-Dev"
},
{
"id":"cluster_drQbdXZl",
"object":"cluster",
"label":"Development"
}
]
}


Note: You will need both the Company ID and Cluster ID in order to manager services inside a specific cluster

 

Examples of Common API commands

Get a list of services inside a cluster

curl -u JBO5z2Ex78p6LmlKV6GyrnwD:HMySkImRY7I0oKX0TWBHWhjSiC9mRQnf --request GET \
  --url https://api.medstack.co/v1/companies/company_YA/clusters/cluster_LB3DGPQx/services \
  --header 'accept: application/json'

The purpose of this request is to retrieve a list of services running on the specified cluster.

 

Output:

{
"object": "list",
"data": [
{
"id": "service_0p40wyadyj6aek1e5banvoatr",
"object": "service",
"name": "mysql-client",
"image": "arey/mysql-client:latest@sha256:664718ad7e477071324e733b79821de2893c96bfaa55684084c3eeb4860b8053",
"replicas": 1,
"command": "tail",
"args": "-f /dev/null",
"hosts": [],
"port": null,
"secrets": [],
"configs": [],
"environment_variables": [],
"mounts": [],
"placement_constraints": ["node.role != manager"]
},
{
"id": "service_uu6464kqbrc51ddxz6nptx7g3",
"object": "service",
"name": "nginx-geoip",
"image": "regserver.bossman.pro/nginx-geoip2:latest@sha256:ccf6a0afd868a3ab004edff7973fe2ad08e8467ca46f7ad262bdea1bf28e33be",
"replicas": 3,
"command": "tail",
"args": "-F /dev/null",
"hosts": ["nginx.bossman.pro"],
"port": 80,
"secrets": [],
"configs": [
{
"id": "v7lwwixp100g8arr9g7brhgn0",
"name": "nginx.conf-geoip-module.14",
"file_name": "/nginx.conf",
"uid": "0",
"gid": "0",
"mode": "400"
},
{
"id": "u86cacj52cnra5ws63btnaomq",
"name": "40x.html",
"file_name": "/usr/share/nginx/html/40x.html",
"uid": "0",
"gid": "0",
"mode": "400"
}
],
"environment_variables": [
{
"key": "NAME",
"value": "Jot"
}
],
"mounts": [
{
"target": "/geoip-data",
"source": "nginx-geo-data",
"readonly": false
}
],
"placement_constraints": []
}
]
}

 

Get a list of Volumes

curl -u JBO5z2Ex78p6LmlKV6GyrnwD:HMySkImRY7I0oKX0TWBHWhjSiC9mRQnf --request GET \
  --url https://api.medstack.co/v1/companies/company_YA/clusters/cluster_LB3DGPQx/volumes \
  --header 'accept: application/json'

 

Output:

{
"object": "list",
"data": [
{
"id": "volume_acme",
"object": "volume",
"name": "acme",
"created": "2023-02-28 20:08:47 UTC",
"service_usage": ["loadbalancer"]
},
{
"id": "volume_datadog-postgres-conf",
"object": "volume",
"name": "datadog-postgres-conf",
"created": "2022-10-07 16:48:59 UTC",
"service_usage": []
}
]
}

Related articles