Getting Started
Getting started using the Atlas system API is pretty straight foward.
Finding your Atlas system.
Ask your system administrator or contact our professional support team if you do not yet know the address of your Atlas System.
To confirm that your atlas system is up and running, type its URL into your favorite web browser.
Using CURL
Curl is a popular system utility to make http requests via the command line.
Open a command line and type man curl, then hit enter to execute this command.
On most unix or linux based systems you should see something like the following
curl(1) Curl Manual curl(1)
NAME
curl - transfer a URL
SYNOPSIS
curl [options / URLs]
DESCRIPTION
curl is a tool to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS,
POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET and TFTP). The command is designed to work without user interaction.
curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, Metalink,
and more. As you will see below, the number of features will make your head spin!
curl is powered by libcurl for all transfer-related features. See libcurl(3) for details.
URL
The URL syntax is protocol-dependent. You'll find a detailed description in RFC 3986.
You can specify multiple URLs or parts of URLs by writing part sets within braces as in:
http://site.{one,two,three}.com
or you can get sequences of alphanumeric series by using [] as in:
ftp://ftp.example.com/file[1-100].txt
ftp://ftp.example.com/file[001-100].txt (with leading zeros)
ftp://ftp.example.com/file[a-z].txt
To test if curl is working type the following command curl google.com
You should receive back something like this.
<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8"> <TITLE>301 Moved</TITLE></HEAD><BODY> <H1>301 Moved</H1> The document has moved <A HREF="http://www.google.com/">here</A>. </BODY></HTML>
This is the contents of the URL 'google.com', which redirects us to the fully qualified (meaning as correctly specified as possible) 'http://www.google.com/'
Making your First Request
Similar to our cUrl request to google, we can make a request to our Atlas System. For our documentation, we will assume your Atlas system is at 192.168.7.76, which is the IPV4 address of an Atlas System called Cash
To test our connection to the system, we can cUrl request a known good route. The easiest route to use for verification, because it does not require authorization, is System Info.
Let’s make a request using curl --insecure https://192.168.7.76/api/v2/info
{
"api_version": "v2.0.0",
"lodestar_version": "2.1.80",
"atlas_version": "2.1.32",
"available_hosts": {
"09e3b2bd": {
"license": {
"valid": true,
"validity": {
"notBefore": "2020-09-09T03:16:21.000Z",
"notAfter": "2020-10-09T03:16:50.000Z"
},
"error": null,
"now": "2020-09-28T21:40:48.043Z"
},
"mac": "00:25:90:fa:51:22",
"application": "atlas",
"version": "2.1.25",
"hostid": "09e3b2bd",
"os_platform": "linux",
"os_release": "4.19.0-11-amd64",
"os_architecture": "x64",
"hostname": "Cash",
"system_uptime": 969968000,
"interfaces": {
"lo": [
{
"address": "127.0.0.1",
"netmask": "255.0.0.0",
"family": "IPv4",
"mac": "00:00:00:00:00:00",
"internal": true,
"cidr": "127.0.0.1/8"
},
{
"address": "::1",
"netmask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
"family": "IPv6",
"mac": "00:00:00:00:00:00",
"internal": true,
"cidr": "::1/128",
"scopeid": 0
}
],
"mgmt0": [
{
"address": "192.168.7.76",
"netmask": "255.255.255.0",
"family": "IPv4",
"mac": "00:25:90:fa:51:22",
"internal": false,
"cidr": "192.168.7.76/24"
},
{
"address": "fe80::225:90ff:fefa:5122",
"netmask": "ffff:ffff:ffff:ffff::",
"family": "IPv6",
"mac": "00:25:90:fa:51:22",
"internal": false,
"cidr": "fe80::225:90ff:fefa:5122/64",
"scopeid": 2
}
],
"bond0": [
{
"address": "10.40.1.76",
"netmask": "255.255.255.0",
"family": "IPv4",
"mac": "00:07:43:38:54:20",
"internal": false,
"cidr": "10.40.1.76/24"
},
{
"address": "fe80::207:43ff:fe38:5420",
"netmask": "ffff:ffff:ffff:ffff::",
"family": "IPv6",
"mac": "00:07:43:38:54:20",
"internal": false,
"cidr": "fe80::207:43ff:fe38:5420/64",
"scopeid": 11
}
]
},
"certificate": null,
"last_contact": 1601330328653,
"local": true,
"address": "192.168.7.76"
},
},
"hostid": "09e3b2bd",
"local": {
"excluded_routes": [
"/api/v1/system/ha/status"
],
"high_availability": false,
"authentication": {
"hinting": true
}
},
"address": "192.168.7.76",
"interfaces": {
"lo": [
{
"address": "127.0.0.1",
"netmask": "255.0.0.0",
"family": "IPv4",
"mac": "00:00:00:00:00:00",
"internal": true,
"cidr": "127.0.0.1/8"
},
{
"address": "::1",
"netmask": "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
"family": "IPv6",
"mac": "00:00:00:00:00:00",
"internal": true,
"cidr": "::1/128",
"scopeid": 0
}
],
"mgmt0": [
{
"address": "192.168.7.76",
"netmask": "255.255.255.0",
"family": "IPv4",
"mac": "00:25:90:fa:51:22",
"internal": false,
"cidr": "192.168.7.76/24"
},
{
"address": "fe80::225:90ff:fefa:5122",
"netmask": "ffff:ffff:ffff:ffff::",
"family": "IPv6",
"mac": "00:25:90:fa:51:22",
"internal": false,
"cidr": "fe80::225:90ff:fefa:5122/64",
"scopeid": 2
}
],
"bond0": [
{
"address": "10.40.1.76",
"netmask": "255.255.255.0",
"family": "IPv4",
"mac": "00:07:43:38:54:20",
"internal": false,
"cidr": "10.40.1.76/24"
},
{
"address": "fe80::207:43ff:fe38:5420",
"netmask": "ffff:ffff:ffff:ffff::",
"family": "IPv6",
"mac": "00:07:43:38:54:20",
"internal": false,
"cidr": "fe80::207:43ff:fe38:5420/64",
"scopeid": 11
}
]
},
"license": {
"valid": true,
"validity": {
"notBefore": "2020-09-09T03:16:21.000Z",
"notAfter": "2020-10-09T03:16:50.000Z"
},
"error": null,
"now": "2020-09-28T21:40:48.043Z"
},
"hostname": "Cash",
"uptime": {
"readable": "Thu Sep 17 2020 09:32:40 GMT-0700",
"unix": 1600360360000
},
"fru": {
"fru_device_description": "Builtin FRU Device (ID 0)",
"board_mfg_date": "Sun Dec 31 16:00:00 1995",
"board_mfg": "Supermicro",
"board_serial": "OM14CS025591",
"product_serial": ""
}
}
Wow! Lots to look at here. Let’s break down our request first.
Our request, curl --insecure https://192.168.7.76/api/v2/info has a couple changes to it.
.Notes
. The API is served only over Secure HTTP. So use https instead of http
. The certifice we ship with to secure our HTTP traffic is not widely circulated, so we must specify --insecure when we curl, or else we will get the following error
open@Cash:~/lodestar$ curl https://192.168.7.76/api/v2/info curl: (60) SSL certificate problem: self signed certificate More details here: https://curl.haxx.se/docs/sslcerts.html curl failed to verify the legitimacy of the server and therefore could not establish a secure connection to it. To learn more about this situation and how to fix it, please visit the web page mentioned above.
A self-signed certificate is not necessarily insecure, but rather, the cUrl program cannot guarantee it is from a well known and trusted source.
A certificate from a well known and trusted source is like a driver’s license from the DMV. It is widely accepted because everyone knows and trusts the source. A self-signed certificate is like you yourself creating an ID card for members of your family. If you are part of the family you know the ID is valid, but others in your local community will not recognize the authority of the issuer.
Making Requests that Require Authorization
If you would like to make further requests using Curl, please generate yourself an Authorization Token from the User Interface or have your system administrator do it for you.
In this example, we will use the dummy example token of thisisanexample.tokenitsnotreal.pleasemakeyourownrealtoken.
To make a request requiring authorization, pass in header information when you make your curl call.
curl --header "token:thisisanexample.tokenitsnotreal.pleasemakeyourownrealtoken" --insecure https://192.168.7.76/api/v2/pool
This request sends you back information on your storage pools.
[
{
"name": "C01",
"size": "3985729650688",
"alloc": "86762832384",
"free": "3898966818304",
"expandsz": "",
"cap": "2",
"dedup": "1.00",
"health": "ONLINE",
"altroot": "",
"autoexpand": "off",
"multihost": "off"
},
{
"name": "D01",
"size": "11991548690432",
"alloc": "17539072",
"free": "11991531151360",
"expandsz": "",
"cap": "0",
"dedup": "1.00",
"health": "ONLINE",
"altroot": "",
"autoexpand": "off",
"multihost": "on"
},
{
"name": "rpool",
"size": "119185342464",
"alloc": "47695052800",
"free": "71490289664",
"expandsz": "",
"cap": "40",
"dedup": "1.00",
"health": "ONLINE",
"altroot": "",
"autoexpand": "off",
"multihost": "off"
}
]
Making Requests with Restful Methods
Up until now we’ve been making cUrl requests that use the default properties of cUrl requests. Now we will override the HTTPS method we are using to be 'POST' instead of 'GET'.
We’re going to now POST a request to the API to find what snapshots exist on our filesystem C01/C01.
Note here the difference in sending multiple headers vs only the token, as well as changing the request type from the default 'GET' to 'POST' along with the JSON data.
curl --header "token:thisisanexample.tokenitsnotreal.pleasemakeyourownrealtoken"\
--header "Content-Type:application/json" \
--request POST \
--data '{"fs":"C01/C01"}' \
--insecure https://192.168.7.76/api/v2/snapshot/find
You might get a long list of snapshots back, depending on your system
[
{
"name": "C01/C01@monkeypaw2",
"created": "Thu Sep 17 20:42 2020",
"fs": "C01/C01",
"time": "monkeypaw2",
"label": ""
},
{
"name": "C01/C01@monkeypaw1",
"created": "Thu Sep 17 20:42 2020",
"fs": "C01/C01",
"time": "monkeypaw1",
"label": ""
},
{
"name": "C01/C01@monkeypaw0",
"created": "Thu Sep 17 20:42 2020",
"fs": "C01/C01",
"time": "monkeypaw0",
"label": ""
}
]
Moving on from Here
This should cover the basics on how to use the command line utility cUrl with your Atlas system. For more on how a specific request is formatted, check the other parts of this manual for that specific request
Using wget
wget formerly Geturl is a computer program that retrieves content from web servers. It supports HTTP, HTTPS, and FTP protocols, as well as retrieval through HTTP proxies.
The wget package is pre-installed on most Linux distributions today. If wget is not installed, you can easily install it using the package manager.
If you need to install it, open a command line and type sudo apt install wget, then hit enter to execute this command.
Making wget request
Let’s make a request using wget https://192.168.7.76/api/v2/info
This will download the contents to a working directory
Our system automatically generates a self signed certificate at installation time. The admin has the option to change the certs to ones that are well known and circulated.
The certificates in either case are secure, it’s just that almost all systems will not immediately recognize the self signed certificate and will have to be configured to accept it as a known provider. In this case you might see the following error:
…
ERROR: The certificate of 192.168.7.76 is not trusted
ERROR: The certificate of 192.168.7.76 doesn’t have a known issuer
…
To fix the error above, add --no-check-certificate option to wget command.
If you would like to make further requests using wget, please generate yourself an Authorization Token from the User Interface or have your system administrator do it for you.
To make a request requiring authorization, pass in header information when you make your wget call.
To make a Post request add --post-data option
For more information on how to use wget type man wget
REST
REST stands for Representational State Transfer. It is a set of rules for creating an API. One of the rules states that you should be able to get some data(called a resource) when you link to a specific URL. Each URL is called a request while the data sent back to you is called a response. It is important to know that request is made up of four things:
The method is the type of request you send to the server. You can choose from these five types below:
These methods provide meaning for the rquest you’re making. They are used to perform four possible actions:
The headers are used to provide information to both the client and the serve. It can be used for purposes such as authentication and providing information about the body content. HTTP Headers are property-value pairs that are separated by a colon.
HTTP Status Codes and Error Messages
Examples
To make requests we can use Postman Software.
Postman is a the collaboration Platform for API development and testing. It is an Open Source Tool and could be easily downloaded.
To get more details on how to use it, visit https://www.postman.com/
Let’s make a GET to get a list of existing pods https://192.168.7.76/api/v2/pod
This request sends you back information on your pods
[
{
"name": "od-pod-goofys3mounter",
"service": {
"id": "od-pod-goofys3mounter.service",
"state": "enabled",
"locked": false
}
},
{
"name": "od-pod-minio-node_red-openldap",
"service": {
"id": "od-pod-minio-node_red-openldap.service",
"state": "failed",
"locked": false
}
},
]
Happy Coding!