Skip to content

Latest commit

 

History

History
370 lines (309 loc) · 22.6 KB

README.md

File metadata and controls

370 lines (309 loc) · 22.6 KB
Raw

Org.OpenAPITools - the C# library for the Public EMMA API

About Infrastructure API

Base URL: https://api.emma.ms/external

This Infrastructure API is for managing the emma cloud infrastructure within a project. The API enables you to view, create, edit, and delete Virtual machines, Spot instances, Applications, Kubernetes clusters, SSH keys, Security groups, and Backup policies. For creating the resources you can use the endpoints with the dictionaries: Data centers, Locations, Providers, Operating systems, Virtual machines configurations, Spot instances configurations, Kubernetes clusters configurations.

Authentication

1. Create service application

To access the API, enter your project, navigate to Settings > Service Apps, and create a service application. Select the access level Read, Operate, or Manage.

  • Read - only GET methods are allowed in the API.

  • Operate - some operations are allowed with the resources (e.g. Start, Reboot, and Shutdown of the Virtual machines).

  • Manage - full creating, updating, and deleting of the resources is allowed.

2. Get access token

  • Copy the Client ID and Client Secret in the service application.
  • Send an API request to the endpoint _/issue-token as specified in the Authentication section of the API documentation. You will receive access and refresh tokens in the response.

For Linux / Mac:

curl -X POST https://api.emma.ms/external/v1/issue-token \\
-H \"Content-Type: application/json\" \\
-d '{\"clientId\": \"YOUR-CLIENT-ID\", \"clientSecret\": \"YOUR-CLIENT-SECRET\"}'

For Windows:

curl -X POST https://api.emma.ms/external/v1/issue-token ^
-H \"Content-Type: application/json\" ^
-d \"{\\\"clientId\\\": \\\"YOUR-CLIENT-ID\\\", \\\"clientSecret\\\": \\\"YOUR-CLIENT-SECRET\\\"}\"

3. Use access token in requests

The Bearer access token is a text string, included in the request header, for example:

For Linux / Mac:

curl -X GET https://api.emma.ms/external/v1/locations -H \"Authorization: Bearer YOUR-ACCESS-TOKEN-HERE\"

Use this token for the API requests.

4. Refresh token

The access token will expire in 10 minutes. A new access token may be created using the refresh token (without Client ID and Client Secret).

To get a new access token send a request to the _/refresh-token endpoint:

For Linux / Mac:

curl -X POST https://api.emma.ms/external/v1/refresh-token \\
-H \"Content-Type: application/json\" \\
-d '{\"refreshToken\": \"YOUR-REFRESH-TOKEN\"}'

Possible response status codes

We use standard HTTP response codes to show the success or failure of requests.

2xx - successful responses.

4xx - client error responses (the response contains an explanation of the error).

5xx - server error responses.

The API uses the following status codes:

| Status Code | Description | Notes | |- -- -- -- -- -- --|- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -|- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -| | 200 | OK | The request was successful. | | 201 | Created | The object was successfully created. This code is only used with objects that are created immediately. | 204 | No content | A successful request, but there is no additional information to send back in the response body (in a case when the object was deleted).
| 400 | Bad Request | The request could not be understood by the server. Incoming parameters might not be valid. | | 401 | Unauthorized | The client is unauthenticated. The client must authenticate itself to get the requested response. | | 403 | Forbidden | The client does not have access rights to the content. | 404 | Not Found | The requested resource is not found. | | 409 | Conflict | This response is sent when a request conflicts with the current state of the object (e.g. deleting the security group with the compute instances in it).| | 422 | Unprocessable Content | The request was well-formed but was unable to be followed due to incorrect field values (e.g. creation of a virtual machine in the non-existent data center). | | 500 | Internal server Error | The server could not return the representation due to an internal server error. |

This C# SDK is automatically generated by the OpenAPI Generator project:

  • API version: 1.0.1
  • SDK version: 1.0.0
  • Generator version: 7.8.0-SNAPSHOT
  • Build package: org.openapitools.codegen.languages.CSharpClientCodegen

Frameworks supported

Dependencies

The DLLs included in the package may not be the latest version. We recommend using NuGet to obtain the latest version of the packages:

Install-Package RestSharp
Install-Package Newtonsoft.Json
Install-Package JsonSubTypes
Install-Package System.ComponentModel.Annotations

NOTE: RestSharp versions greater than 105.1.0 have a bug which causes file uploads to fail. See RestSharp#742. NOTE: RestSharp for .Net Core creates a new socket for each api call, which can lead to a socket exhaustion problem. See RestSharp#1406.

Installation

Run the following command to generate the DLL

  • [Mac/Linux] /bin/sh build.sh
  • [Windows] build.bat

Then include the DLL (under the bin folder) in the C# project, and use the namespaces:

using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;

Packaging

A .nuspec is included with the project. You can follow the Nuget quickstart to create and publish packages.

This .nuspec uses placeholders from the .csproj, so build the .csproj directly:

nuget pack -Build -OutputDirectory out Org.OpenAPITools.csproj

Then, publish to a local feed or other host and consume the new package via Nuget as usual.

Usage

To use the API client with a HTTP proxy, setup a System.Net.WebProxy

Configuration c = new Configuration();
System.Net.WebProxy webProxy = new System.Net.WebProxy("http://myProxyUrl:80/");
webProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
c.Proxy = webProxy;

Getting Started

using System.Collections.Generic;
using System.Diagnostics;
using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;

namespace Example
{
    public class Example
    {
        public static void Main()
        {

            Configuration config = new Configuration();
            config.BasePath = "https://api.emma.ms/external";
            var apiInstance = new AuthenticationApi(config);
            var credentials = new Credentials?(); // Credentials? |  (optional) 

            try
            {
                // Issue token
                Token result = apiInstance.IssueToken(credentials);
                Debug.WriteLine(result);
            }
            catch (ApiException e)
            {
                Debug.Print("Exception when calling AuthenticationApi.IssueToken: " + e.Message );
                Debug.Print("Status Code: "+ e.ErrorCode);
                Debug.Print(e.StackTrace);
            }

        }
    }
}

Documentation for API Endpoints

All URIs are relative to https://api.emma.ms/external

Class Method HTTP request Description
AuthenticationApi IssueToken POST /v1/issue-token Issue token
AuthenticationApi RefreshToken POST /v1/refresh-token Refresh token
ComputeInstancesConfigurationsApi GetKuberNodesConfigs GET /v1/kubernetes-configs List of available configurations for Kubernetes cluster node
ComputeInstancesConfigurationsApi GetSpotConfigs GET /v1/spots-configs List of available configurations for spot instance creation
ComputeInstancesConfigurationsApi GetVmConfigs GET /v1/vms-configs List of available configurations for virtual machine creation
DataCentersApi GetDataCenter GET /v1/data-centers/{dataCenterId} Get data center by ID
DataCentersApi GetDataCenters GET /v1/data-centers Get list of data centers
KubernetesClustersApi CreateKubernetesCluster POST /v1/kubernetes Create Kubernetes cluster
KubernetesClustersApi DeleteKubernetesCluster DELETE /v1/kubernetes/{kubernetesId} Delete Kubernetes cluster
KubernetesClustersApi EditKubernetesCluster PUT /v1/kubernetes/{kubernetesId} Edit Kubernetes cluster
KubernetesClustersApi GetKubernetesCluster GET /v1/kubernetes/{kubernetesId} Get Kubernetes cluster by id
KubernetesClustersApi GetKubernetesClusters GET /v1/kubernetes Get list of Kubernetes clusters
LocationsApi GetLocation GET /v1/locations/{locationId} Get location by ID
LocationsApi GetLocations GET /v1/locations Get list of locations
OperatingSystemsApi GetOperatingSystem GET /v1/operating-systems/{operatingSystemId} Get operating system by ID
OperatingSystemsApi GetOperatingSystems GET /v1/operating-systems Get list of operating systems
ProvidersApi GetProvider GET /v1/providers/{providerId} Get cloud provider by ID
ProvidersApi GetProviders GET /v1/providers Get list of cloud providers
SSHKeysApi GetSshKey GET /v1/ssh-keys/{sshKeyId} Get SSH key by id
SSHKeysApi SshKeyDelete DELETE /v1/ssh-keys/{sshKeyId} Delete SSH keys
SSHKeysApi SshKeyUpdate PUT /v1/ssh-keys/{sshKeyId} Update SSH keys
SSHKeysApi SshKeys GET /v1/ssh-keys Get list of SSH keys
SSHKeysApi SshKeysCreateImport POST /v1/ssh-keys Create or import SSH key
SecurityGroupsApi GetSecurityGroup GET /v1/security-groups/{securityGroupId} Get security group by ID
SecurityGroupsApi GetSecurityGroups GET /v1/security-groups Get list of security groups
SecurityGroupsApi SecurityGroupCreate POST /v1/security-groups Create security group
SecurityGroupsApi SecurityGroupDelete DELETE /v1/security-groups/{securityGroupId} Delete security group
SecurityGroupsApi SecurityGroupInstanceAdd POST /v1/security-groups/{securityGroupId}/instances Add instance to security group
SecurityGroupsApi SecurityGroupInstances GET /v1/security-groups/{securityGroupId}/instances Get instances in security group
SecurityGroupsApi SecurityGroupUpdate PUT /v1/security-groups/{securityGroupId} Update security group
SpotInstancesApi GetSpot GET /v1/spot-instances/{spotInstanceId} Get spot instance by ID
SpotInstancesApi GetSpots GET /v1/spot-instances Get list of spot instances
SpotInstancesApi SpotActions POST /v1/spot-instances/{spotInstanceId}/actions Perform actions with a spot instance
SpotInstancesApi SpotCreate POST /v1/spot-instances Create spot instance
SpotInstancesApi SpotDelete DELETE /v1/spot-instances/{spotInstanceId} Delete spot instance
StatisticsApi GetStatisticalData POST /v1/statistics/retrieve Extract data from the DWH
SubnetworksApi V1SubnetworksGet GET /v1/subnetworks Get list of subnetworks
SubnetworksApi V1SubnetworksPost POST /v1/subnetworks Create subnetwork
SubnetworksApi V1SubnetworksSubnetworkIdDelete DELETE /v1/subnetworks/{subnetworkId} Delete subnetwork
SubnetworksApi V1SubnetworksSubnetworkIdGet GET /v1/subnetworks/{subnetworkId} Get subnetwork by ID
SubnetworksApi V1SubnetworksSubnetworkIdPut PUT /v1/subnetworks/{subnetworkId} Update subnetwork
VirtualMachinesApi GetVm GET /v1/vms/{vmId} Get virtual machine by id
VirtualMachinesApi GetVms GET /v1/vms Get list of virtual machines
VirtualMachinesApi VmActions POST /v1/vms/{vmId}/actions Perform actions with a virtual machine
VirtualMachinesApi VmCreate POST /v1/vms Create virtual machine
VirtualMachinesApi VmDelete DELETE /v1/vms/{vmId} Delete virtual machine

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

bearerAuth

  • Type: Bearer Authentication