# 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:

* [MetalSoft postman workspace](https://www.postman.com/metalsoft/workspace/metalsoft-team-workspace/overview)

## 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.

![](/assets/guides/retrieving_my_api_key_01.png){w=400px align=center}

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

![](/assets/guides/retrieving_my_api_key_02.png)

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:
![](http://us01.metalsoft.io/api/developer/developer#documents/3)

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

* [API Reference](https://us01.metalsoft.io/api/developer/developer#documents/3)

## 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](https://github.com/metalsoft-io/scripts/tree/main/api-examples) and the [API documentation](https://us01.metalsoft.io/api/developer/developer#documents/3)
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:

* [MetalSoft Postman workspace](https://www.postman.com/metalsoft/workspace/metalsoft-team-workspace/overview)
* [API Reference](https://us01.metalsoft.io/api/developer/developer#documents/3)

#### 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](https://github.com/metalsoft-io/scripts/tree/main/api-examples) and the [API documentation](https://us01.metalsoft.io/api/developer/developer#documents/3)
4. `Oauth2` flow with the API key.

#### Object Schemas

Here are some MetalSoft objects and their relationships.

![](/assets/general/developer_getting_started_03.svg)

* **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.
:::
3. **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.
4. **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](https://us01.metalsoft.io/api/developer/developer#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.