Connecting to the API

The MetalSoft uses an RPC-style API accessed over HTTP.

For a quick getting started with it use the Postman collections:

The API endpoint:

The API endpoint is found at:

  • Admin level operations: https://<environment_hostname>/api/developer/developer

  • User level operations: https://<environment_hostname>/api/

Important

Note that the same operations on different endpoints may have different parameters and different behavior. Always check that the documentation being read is that of the endpoint being called. The URLs are the same.

Retrieving my API key and connecting to the endpoint

Login then click on API credentials on the upper right corner.

Then click on the API key input to display your API key.

The API key can be regenerated if it is compromised by clicking the “Generate a new key” button.

API Reference

Accessing the same API endpoints from a browser will open the API documentation:

Here is one from our demo environments:

Typically, the portal will create infrastructures and configure servers, storage and network configurations. The following is a postman collection with sample infrastructure related operations:

Authenticating to the API

API users can use the following methods to authenticate HTTP requests:

  1. Authorization: Bearer <API_Key> header. This is the recommended method.

  2. ?verify=<user_id:signature> http query param where the signature value is calculated as a HEX digest of the MD5 sum of the body with the API key as the key. This is the most secure method as it prevents reply attacks but it is more complicated to operate. Consult the following examples and the API documentation

  3. Basic authentication, with the username and password of a user. Not recommended except when using CURL or other quick scripts.

  4. Oauth2 flow with the API key.

Note that the API key can be regenerated at any time using the UI.

Interacting with the API

Typically, the portal will create infrastructures and configure servers, storage and network configurations. The following is a Postman collection with sample infrastructure related operations:

Authenticating to the API

API users can use the following methods to authenticate HTTP requests:

  1. Authorization: Bearer <API_Key> header.

  2. Basic authentication, with the username and password of a user.

  3. ?verify=<user_id:signature> http query param where the signature value is calculated as a HEX digest of the MD5 sum of the body with the API key as the key. This is the most secure method as it prevents reply attacks but it is more complicated to operate. Consult the following examples and the API documentation

  4. Oauth2 flow with the API key.

Object Schemas

Here are some MetalSoft objects and their relationships.

  • Infrastructure - A grouping of resources such as Servers, Networks and storage, usually around an application

  • Instance - A mapping to a physical server that has properties such as a server, IP addresses, hostname, drives attached etc.

  • Instance Array - A group of instances that are managed as a single entity

  • Drive - A block device that can be attached to an instance. Can be iSCSI or FC. Can be cloned from an existing volume template or be unformatted.

  • Drive Array - A group of drives

  • Network - A MetalSoft specific abstract construct that informs the system how the network is to be configured. The default behavior is to map a network to a dedicated L2 network but it can be changed via Network Profiles.

  • Network Profile - A policy that defines how an instance is connected to a network. It defines one or more overlay networks (called VLANs but they can map to other implementations). It also defines which subnet pools to be used to allocate subnets and hence IPs within this network.

  • Subnet Pool - A subnet prefix out of which smaller prefixes are allocated to an L2 network

  • Subnet - A smaller prefix mapped to an L2 network from which IPs are allocated. The first IPs are usually the gateway Ips.

  • Subscriptions - Billing helper concept used to store information that can be used to charge a different price for “reserved” instances as opposed to on-demand.

IDs and labels

Note that most of the objects use multiple forms of identification:

  1. ID such as 22, 33, which we refer to in the UI as #12. The IDs are unique auto-incremented integers and can safely be used in all programmatic contexts.

  2. Label such as my-infrastructure. These are strings that are usually unique within certain contexts. Such as a user can only have one my-infrastructure but two different users can have the same label. End-users can set these labels via the UI. Developers should use the labels carefully as overlaps may happen when managing multiple objects of multiple users.

Important

IDs are not reused. For example if the’my-infrastructure’ infrastructure is deleted and then re-created a new ID will be assigned.

  1. Subdomain such as my-infrastructure.7.us01.metalsoft.io. This is a mechanism to remove the overlap between the various labels by providing a unique identifying string. It is intended for use with human readable tools such as the CLI.

  2. Subdomain permanent such as infrastructure-704.us01.metalsoft.io. This is a string that is guarantied to be unique and often incorporates the ID.

Decrypting credentials

All credentials in objects are encrypted and when retrieved in objects they are provided in their encrypted form to prevent accidental leaks in logs etc. Some SDKs such as the GO one provides facilities to decrypt this on the fly.

If you use the API directly you need to use the password_decrypt function to decrypt them. Provide the component of the retrieved string that is after the “:”.

Important

The user retrieving credentials must have the appropriate permissions in Users > user > Credentials access to access the passwords even if they have a role such as full admin. By default these permissions are set to false.