diff --git a/cmd/objects/create.go b/cmd/objects/create.go index 43a737a..4497007 100644 --- a/cmd/objects/create.go +++ b/cmd/objects/create.go @@ -49,16 +49,18 @@ func PutObject(localPath string, isDir bool, s3Prefix string, s3Client *minio.Cl defer object.Close() objectStat, err := object.Stat() + if err != nil { log.Fatal(fmt.Sprintf("Could not read file properties %v. Got error %v", localPath, err)) } - _, err = s3Client.PutObject(context.Background(), createObjectBucketName, s3Path, object, objectStat.Size(), minio.PutObjectOptions{ContentType: "application/octet-stream"}) + _, err = s3Client.FPutObject(context.Background(), createObjectBucketName, objectStat.Name(), s3Path, minio.PutObjectOptions{ContentType: "application/octet-stream"}) if err != nil { if s.Contains(err.Error(), "API rate limit exceeded") { // retry in case of rate limit exceeded eror time.Sleep(1000 * time.Millisecond) - _, err = s3Client.PutObject(context.Background(), createObjectBucketName, s3Path, object, objectStat.Size(), minio.PutObjectOptions{ContentType: "application/octet-stream"}) + _, err = s3Client.FPutObject(context.Background(), createObjectBucketName, objectStat.Name(), s3Path, minio.PutObjectOptions{ContentType: "application/octet-stream"}) + if err != nil { log.Fatal(fmt.Sprintf("Could not create object file %v. Got error %v", s3Path, err)) } @@ -80,6 +82,7 @@ func PutObject(localPath string, isDir bool, s3Prefix string, s3Client *minio.Cl } _, err := s3Client.PutObject(context.Background(), createObjectBucketName, s3Path, nil, 0, minio.PutObjectOptions{}) + if err != nil { if s.Contains(err.Error(), "API rate limit exceeded") { // retry in case of rate limit exceeded eror time.Sleep(1000 * time.Millisecond) @@ -138,6 +141,7 @@ var objectCreateCmd = &cobra.Command{ ), Secure: true, }) + if err != nil { log.Fatal(fmt.Sprintf("Error in connecting to S3 Client . Got error %v", err)) } diff --git a/go.mod b/go.mod index 7296925..de9e3c7 100644 --- a/go.mod +++ b/go.mod @@ -1,25 +1,59 @@ module contabo.com/cli/cntb -go 1.16 +go 1.21 + +toolchain go1.22.0 require ( contabo.com/cli/cntb/openapi v0.0.0-00010101000000-000000000000 - github.com/PaesslerAG/gval v1.1.2 // indirect github.com/PaesslerAG/jsonpath v0.1.1 github.com/golang-jwt/jwt v3.2.2+incompatible - github.com/gorilla/websocket v1.5.0 // indirect github.com/hprose/hprose-go v0.0.0-20161031134501-83de97da5004 - github.com/minio/minio-go/v7 v7.0.23 + github.com/minio/minio-go/v7 v7.0.68 github.com/mitchellh/go-homedir v1.1.0 github.com/olekukonko/tablewriter v0.0.5 github.com/satori/go.uuid v1.2.0 - github.com/sirupsen/logrus v1.8.1 + github.com/sirupsen/logrus v1.9.2 github.com/spf13/cobra v1.2.1 github.com/spf13/viper v1.9.0 - golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd // indirect golang.org/x/oauth2 v0.0.0-20210819190943-2bc19b11175f gopkg.in/yaml.v2 v2.4.0 sigs.k8s.io/yaml v1.3.0 ) +require ( + github.com/PaesslerAG/gval v1.1.2 // indirect + github.com/dustin/go-humanize v1.0.1 // indirect + github.com/fsnotify/fsnotify v1.5.1 // indirect + github.com/golang/protobuf v1.5.2 // indirect + github.com/google/uuid v1.6.0 // indirect + github.com/gorilla/websocket v1.5.0 // indirect + github.com/hashicorp/hcl v1.0.0 // indirect + github.com/inconshreveable/mousetrap v1.0.0 // indirect + github.com/json-iterator/go v1.1.12 // indirect + github.com/klauspost/compress v1.17.6 // indirect + github.com/klauspost/cpuid/v2 v2.2.6 // indirect + github.com/magiconair/properties v1.8.5 // indirect + github.com/mattn/go-runewidth v0.0.9 // indirect + github.com/minio/md5-simd v1.1.2 // indirect + github.com/minio/sha256-simd v1.0.1 // indirect + github.com/mitchellh/mapstructure v1.4.2 // indirect + github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect + github.com/modern-go/reflect2 v1.0.2 // indirect + github.com/pelletier/go-toml v1.9.4 // indirect + github.com/rs/xid v1.5.0 // indirect + github.com/spf13/afero v1.6.0 // indirect + github.com/spf13/cast v1.4.1 // indirect + github.com/spf13/jwalterweatherman v1.1.0 // indirect + github.com/spf13/pflag v1.0.5 // indirect + github.com/subosito/gotenv v1.2.0 // indirect + golang.org/x/crypto v0.19.0 // indirect + golang.org/x/net v0.21.0 // indirect + golang.org/x/sys v0.17.0 // indirect + golang.org/x/text v0.14.0 // indirect + google.golang.org/appengine v1.6.7 // indirect + google.golang.org/protobuf v1.27.1 // indirect + gopkg.in/ini.v1 v1.67.0 // indirect +) + replace contabo.com/cli/cntb/openapi => ./openapi diff --git a/go.sum b/go.sum index 9704792..97354ee 100644 --- a/go.sum +++ b/go.sum @@ -75,8 +75,8 @@ github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsr github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/dustin/go-humanize v1.0.0 h1:VSnTsYCnlFHaM2/igO1h6X3HA71jcobQuxemgkq4zYo= -github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk= +github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY= +github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto= github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4= github.com/envoyproxy/go-control-plane v0.9.1-0.20191026205805-5f8ba28d4473/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4= github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98= @@ -165,9 +165,9 @@ github.com/google/pprof v0.0.0-20210601050228-01bbb1931b22/go.mod h1:kpwsk12EmLe github.com/google/pprof v0.0.0-20210609004039-a478d1d731e9/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= github.com/google/pprof v0.0.0-20210720184732-4bb14d4b1be1/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= github.com/google/renameio v0.1.0/go.mod h1:KWCgfxg9yswjAJkECMjeO8J8rahYeXnNhOm40UhjYkI= -github.com/google/uuid v1.1.1/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= -github.com/google/uuid v1.1.2 h1:EVhdT+1Kseyi1/pUmXKaFxYsDNy9RQYkMWRH68J/W7Y= github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/googleapis/gax-go/v2 v2.0.4/go.mod h1:0Wqv26UfaUD9n4G6kQubkQ+KchISgw+vpHVxEJEs9eg= github.com/googleapis/gax-go/v2 v2.0.5/go.mod h1:DWXyrwAJ9X0FpwwEdw+IPEYBICEFu5mhpdKc/us6bOk= github.com/googleapis/gax-go/v2 v2.1.0/go.mod h1:Q3nei7sK6ybPYH7twZdmQpAd1MKb7pfu6SK+H1/DsU0= @@ -210,19 +210,19 @@ github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1: github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc= github.com/inconshreveable/mousetrap v1.0.0 h1:Z8tu5sraLXCXIcARxBp/8cbvlwVa7Z1NHg9XEKhtSvM= github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8= -github.com/json-iterator/go v1.1.10/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4= -github.com/json-iterator/go v1.1.11 h1:uVUAXhF2To8cbw/3xN3pxj6kk7TYKs98NIrTqPlMWAQ= github.com/json-iterator/go v1.1.11/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4= +github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM= +github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo= github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1:6v2b51hI/fHJwM22ozAgKL4VKDeJcHhJFhtBdhmNjmU= github.com/jstemmer/go-junit-report v0.9.1/go.mod h1:Brl9GWCQeLvo8nXZwPNNblvFj/XSXhF0NWZEnDohbsk= github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU= github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8= github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck= -github.com/klauspost/compress v1.13.5 h1:9O69jUPDcsT9fEm74W92rZL9FQY7rCdaXVneq+yyzl4= -github.com/klauspost/compress v1.13.5/go.mod h1:/3/Vjq9QcHkK5uEr5lBEmyoZ1iFhe47etQ6QUkpK6sk= -github.com/klauspost/cpuid v1.2.3/go.mod h1:Pj4uuM528wm8OyEC2QMXAi2YiTZ96dNQPGgoMS4s3ek= -github.com/klauspost/cpuid v1.3.1 h1:5JNjFYYQrZeKRJ0734q51WCEEn2huer72Dc7K+R/b6s= -github.com/klauspost/cpuid v1.3.1/go.mod h1:bYW4mA6ZgKPob1/Dlai2LviZJO7KGI3uoWLd42rAQw4= +github.com/klauspost/compress v1.17.6 h1:60eq2E/jlfwQXtvZEeBUYADs+BwKBWURIY+Gj2eRGjI= +github.com/klauspost/compress v1.17.6/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM= +github.com/klauspost/cpuid/v2 v2.0.1/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg= +github.com/klauspost/cpuid/v2 v2.2.6 h1:ndNyv040zDGIDh8thGkXYjnFtiN02M1PVVF+JE/48xc= +github.com/klauspost/cpuid/v2 v2.2.6/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws= github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg= github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= github.com/kr/pretty v0.2.0 h1:s5hAObm+yFO5uHYt5dYjxi2rXrsnmRpJx4OYvIWUaQs= @@ -244,12 +244,12 @@ github.com/mattn/go-runewidth v0.0.9 h1:Lm995f3rfxdpd6TSmuVCHVb/QhupuXlYr8sCI/Qd github.com/mattn/go-runewidth v0.0.9/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI= github.com/miekg/dns v1.0.14/go.mod h1:W1PPwlIAgtquWBMBEV9nkV9Cazfe8ScdGz/Lj7v3Nrg= github.com/miekg/dns v1.1.26/go.mod h1:bPDLeHnStXmXAq1m/Ch/hvfNHr14JKNPMBo3VZKjuso= -github.com/minio/md5-simd v1.1.0 h1:QPfiOqlZH+Cj9teu0t9b1nTBfPbyTl16Of5MeuShdK4= -github.com/minio/md5-simd v1.1.0/go.mod h1:XpBqgZULrMYD3R+M28PcmP0CkI7PEMzB3U77ZrKZ0Gw= -github.com/minio/minio-go/v7 v7.0.23 h1:NleyGQvAn9VQMU+YHVrgV4CX+EPtxPt/78lHOOTncy4= -github.com/minio/minio-go/v7 v7.0.23/go.mod h1:ei5JjmxwHaMrgsMrn4U/+Nmg+d8MKS1U2DAn1ou4+Do= -github.com/minio/sha256-simd v0.1.1 h1:5QHSlgo3nt5yKOJrC7W8w7X+NFl8cMPZm96iu8kKUJU= -github.com/minio/sha256-simd v0.1.1/go.mod h1:B5e1o+1/KgNmWrSQK08Y6Z1Vb5pwIktudl0J58iy0KM= +github.com/minio/md5-simd v1.1.2 h1:Gdi1DZK69+ZVMoNHRXJyNcxrMA4dSxoYHZSQbirFg34= +github.com/minio/md5-simd v1.1.2/go.mod h1:MzdKDxYpY2BT9XQFocsiZf/NKVtR7nkE4RoEpN+20RM= +github.com/minio/minio-go/v7 v7.0.68 h1:hTqSIfLlpXaKuNy4baAp4Jjy2sqZEN9hRxD0M4aOfrQ= +github.com/minio/minio-go/v7 v7.0.68/go.mod h1:XAvOPJQ5Xlzk5o3o/ArO2NMbhSGkimC+bpW/ngRKDmQ= +github.com/minio/sha256-simd v1.0.1 h1:6kaan5IFmwTNynnKKpDHe6FWHohJOHhCPchzK49dzMM= +github.com/minio/sha256-simd v1.0.1/go.mod h1:Pz6AKMiUdngCLpeTL/RJY1M9rUuPMYujV5xJjtbRSN8= github.com/mitchellh/cli v1.0.0/go.mod h1:hNIlj7HEI86fIcpObd7a0FcrxTWetlwJDGcceTlRvqc= github.com/mitchellh/cli v1.1.0/go.mod h1:xcISNoH86gajksDmfB23e/pu+B+GeFRMYmoHXxx3xhI= github.com/mitchellh/go-homedir v1.0.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0= @@ -267,8 +267,9 @@ github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0= -github.com/modern-go/reflect2 v1.0.1 h1:9f412s+6RmYXLWZSEzVVgPGK7C2PphHj5RJrvfx9AWI= github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0= +github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M= +github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk= github.com/olekukonko/tablewriter v0.0.5 h1:P2Ga83D34wi1o9J6Wh1mRuqd4mF/x/lgBS7N7AbDhec= github.com/olekukonko/tablewriter v0.0.5/go.mod h1:hPp6KlRPjbx+hW8ykQs1w3UBbZlj6HuIJcUGPhkA7kY= github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc= @@ -284,8 +285,8 @@ github.com/posener/complete v1.2.3/go.mod h1:WZIdtGGp+qx0sLrYKtIRAruyNpv6hFCicSg github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA= github.com/rogpeppe/fastuuid v1.2.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ= github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4= -github.com/rs/xid v1.2.1 h1:mhH9Nq+C1fY2l1XIpgxIiUOfNpRBYH1kKcr+qfKgjRc= -github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ= +github.com/rs/xid v1.5.0 h1:mKX4bl4iPYJtEIxp6CYiUuLQ/8DYMoz0PUdtGgMFRVc= +github.com/rs/xid v1.5.0/go.mod h1:trrq9SKmegXys3aeAKXMUTdJsYXVwGY3RLcfgqegfbg= github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts= github.com/sagikazarmark/crypt v0.1.0/go.mod h1:B/mN0msZuINBtQ1zZLEQcegFJJf9vnYIR88KRMEuODE= @@ -293,8 +294,8 @@ github.com/satori/go.uuid v1.2.0 h1:0uYX9dsZ2yD7q2RtLRtPSdGDWzjeM3TbMJP9utgA0ww= github.com/satori/go.uuid v1.2.0/go.mod h1:dA0hQrYB0VpLJoorglMZABFdXlWrHn1NEOzdhQKdks0= github.com/sean-/seed v0.0.0-20170313163322-e2103e2c3529/go.mod h1:DxrIzT+xaE7yg65j358z/aeFdxmN0P9QXhEzd20vsDc= github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc= -github.com/sirupsen/logrus v1.8.1 h1:dJKuHgqk1NNQlqoA6BTlM1Wf9DOH3NBjQyu0h9+AZZE= -github.com/sirupsen/logrus v1.8.1/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0= +github.com/sirupsen/logrus v1.9.2 h1:oxx1eChJGI6Uks2ZC4W1zpLlVgqB8ner4EuQwV4Ik1Y= +github.com/sirupsen/logrus v1.9.2/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ= github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc= github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA= github.com/spaolacci/murmur3 v0.0.0-20180118202830-f09979ecbc72/go.mod h1:JwIasOWyU6f++ZhiEuf87xNszmSA2myDM2Kzu9HwQUA= @@ -349,9 +350,9 @@ golang.org/x/crypto v0.0.0-20190820162420-60c769a6c586/go.mod h1:yigFU9vqHzYiE8U golang.org/x/crypto v0.0.0-20190923035154-9ee001bba392/go.mod h1:/lpIB1dKB+9EgE3H3cr1v9wB50oz8l4C4h62xy7jSTY= golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI= golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= -golang.org/x/crypto v0.0.0-20201216223049-8b5274cf687f/go.mod h1:jdWPYTVW3xRLrWPugEBEK3UY2ZEsg3UU495nc5E+M+I= -golang.org/x/crypto v0.0.0-20210817164053-32db794688a5 h1:HWj/xjIHfjYU5nVXpTM0s39J9CbLn7Cc5a7IC5rwsMQ= golang.org/x/crypto v0.0.0-20210817164053-32db794688a5/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= +golang.org/x/crypto v0.19.0 h1:ENy+Az/9Y1vSrlrvBSyna3PITt4tiZLf7sgCjZBX7Wo= +golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU= golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA= golang.org/x/exp v0.0.0-20190306152737-a1d7652674e8/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA= golang.org/x/exp v0.0.0-20190510132918-efd6b22b2522/go.mod h1:ZjyILWgesfNpC6sMxTJOJm9Kp84zZh5NQWvqDGG3Qr8= @@ -425,8 +426,8 @@ golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v golang.org/x/net v0.0.0-20210316092652-d523dce5a7f4/go.mod h1:RBQZq4jEuRlivfhVLdyRGr576XBO4/greRjx4P4O3yc= golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM= golang.org/x/net v0.0.0-20210503060351-7fd8e65b6420/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y= -golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd h1:O7DYs+zxREGLKzKoMQrtrEacpb0ZVXA5rIwylE2Xchk= -golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd/go.mod h1:CfG3xpIq0wQ8r1q4Su4UZFWDARRcnwPjda9FqA0JpMk= +golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4= +golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44= golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U= golang.org/x/oauth2 v0.0.0-20190226205417-e64efc72b421/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw= golang.org/x/oauth2 v0.0.0-20190604053449-0f29369cfe45/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw= @@ -489,7 +490,6 @@ golang.org/x/sys v0.0.0-20200501052902-10377860bb8e/go.mod h1:h1NjWce9XRLGQEsW7w golang.org/x/sys v0.0.0-20200511232937-7e40ca221e25/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200515095857-1151b9dac4a9/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200523222454-059865788121/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.0.0-20200625212154-ddb9806d33ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200803210538-64077c9b5642/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200905004654-be1d3432aa8f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= @@ -512,11 +512,11 @@ golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBc golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20210806184541-e5e7981a1069/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.0.0-20210823070655-63515b42dcdf/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e h1:fLOSk5Q00efkSvAm+4xcoXD+RRmLmmulPn5I3Y9F2EM= -golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw= +golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.17.0 h1:25cE3gD+tdBA7lp7QfhuV+rJiE9YXTcS3VG1SqssI/Y= +golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= -golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.1-0.20180807135948-17ff2d5776d2/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= @@ -525,8 +525,8 @@ golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.4/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.5/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= -golang.org/x/text v0.3.7 h1:olpwvP2KacW1ZWvsR7uQhoyTYvKAupfQrRGBFM352Gk= -golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= +golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= +golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= golang.org/x/time v0.0.0-20181108054448-85acf8d2951c/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= golang.org/x/time v0.0.0-20190308202827-9d24e82272b4/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= golang.org/x/time v0.0.0-20191024005414-555d28b269f0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= @@ -724,10 +724,10 @@ gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo= gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI= -gopkg.in/ini.v1 v1.57.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= gopkg.in/ini.v1 v1.62.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= -gopkg.in/ini.v1 v1.63.2 h1:tGK/CyBg7SMzb60vP1M03vNZ3VDu3wGQJwn7Sxi9r3c= gopkg.in/ini.v1 v1.63.2/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= +gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA= +gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.3/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= diff --git a/openapi/.openapi-generator/FILES b/openapi/.openapi-generator/FILES index 292bcee..881b83a 100644 --- a/openapi/.openapi-generator/FILES +++ b/openapi/.openapi-generator/FILES @@ -1,4 +1,5 @@ .gitignore +.openapi-generator-ignore .travis.yml README.md api/openapi.yaml diff --git a/openapi/README.md b/openapi/README.md index 74f0121..4504c0c 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -78,6 +78,7 @@ Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'G + ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` @@ -94,6 +95,7 @@ Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'G + ```sh # get list of your instances cntb get instances @@ -147,6 +149,7 @@ If you need to allow other persons or automation scripts to access specific API + This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` @@ -159,6 +162,7 @@ If you need to allow other persons or automation scripts to access specific API + In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. diff --git a/openapi/api/openapi.yaml b/openapi/api/openapi.yaml index 55ba510..8a4db08 100644 --- a/openapi/api/openapi.yaml +++ b/openapi/api/openapi.yaml @@ -82,6 +82,7 @@ info: + ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` @@ -98,6 +99,7 @@ info: + ```sh # get list of your instances cntb get instances @@ -151,6 +153,7 @@ info: + This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` @@ -163,6 +166,7 @@ info: + In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. @@ -346,10 +350,13 @@ tags: - description: Tickets API name: Tickets paths: - /v1/users: - get: - description: List and filter all your users. - operationId: retrieveUserList + /v1/compute/instances/{instanceId}/actions/start: + post: + description: Starting a compute instance / resource is like powering on a real + server. If the compute instance / resource is already started nothing will + happen. You may check the current status anytime when getting information + about a compute instance / resource. + operationId: start parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -371,92 +378,39 @@ paths: schema: type: string style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false - schema: - format: int64 - type: integer - style: form - - description: Number of elements per page. - example: 10 - explode: true - in: query - name: size - required: false + - description: The identifier of the compute instance / resource to be started + in rescue mode. + example: 12345 + explode: false + in: path + name: instanceId + required: true schema: format: int64 type: integer - style: form - - description: Specify fields and ordering (ASC for ascending, DESC for descending) - in following format `field:ASC|DESC`. - example: name:asc - explode: true - in: query - name: orderBy - required: false - schema: - items: - type: string - type: array - style: form - - description: Filter as substring match for user emails. - example: john.doe@example.com - explode: true - in: query - name: email - required: false - schema: - type: string - style: form - - description: Filter if user is enabled or not. - example: "true" - explode: true - in: query - name: enabled - required: false - schema: - type: boolean - style: form - - description: Filter if user is owner or not. - example: "true" - explode: true - in: query - name: owner - required: false - schema: - type: boolean - style: form + style: simple responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/ListUserResponse' - description: The response will be a JSON object and contains a paginated - list of users. + $ref: '#/components/schemas/InstanceStartActionResponse' + description: Information of started instance security: - bearer: [] - summary: List users + summary: Start a compute instance / resource identified by its id tags: - - Users + - Instance Actions x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/users'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' + source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/start"' - lang: cntb CLI - source: cntb get users + source: cntb start instance 1234 + /v1/compute/instances/{instanceId}/actions/restart: post: - description: Create a new user with required attributes name, email, enabled, - totp (=Two-factor authentication 2FA), admin (=access to all endpoints and - resources), accessAllResources and roles. You can't specify any password / - secrets for the user. For security reasons the user will have to specify secrets - on his own. - operationId: createUser + description: List of your custom images history, with the ability to apply filters. + operationId: restart parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -478,41 +432,44 @@ paths: schema: type: string style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserRequest' + - description: The identifier of the compute instance / resource to be started + in rescue mode. + example: 12345 + explode: false + in: path + name: instanceId required: true + schema: + format: int64 + type: integer + style: simple responses: "201": content: application/json: schema: - $ref: '#/components/schemas/CreateUserResponse' - description: The response will be a JSON object and contains standard user - attributes. + $ref: '#/components/schemas/InstanceRestartActionResponse' + description: Information of restarted instance security: - bearer: [] - summary: Create a new user + summary: Retrieve a list of your custom images history. tags: - - Users + - Instance Actions x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/users'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{ - "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", - "enabled": true, "totp": false, "locale": "en", "roles": [2]}''' + source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/restart"' - lang: cntb CLI - source: cntb create user --firstName John --lastName Doe --email john.doe@example.com - --enabled --locale en --roles 2 - /v1/users/{userId}: - delete: - description: By deleting a user he will not be able to access any endpoints - or resources any longer. In order to temporarily disable a user please update - its `enabled` attribute. - operationId: deleteUser + source: cntb restart instance 1234 + /v1/compute/instances/{instanceId}/actions/stop: + post: + description: Stopping a compute instance / resource is like powering off a real + server. So please be aware that data may be lost. Alternatively you may log + in and shut your compute instance / resource gracefully via the operating + system. If the compute instance / resource is already stopped nothing will + happen. You may check the current status anytime when getting information + about a compute instance / resource. + operationId: stop parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -534,34 +491,41 @@ paths: schema: type: string style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - description: The identifier of the compute instance / resource to be started + in rescue mode. + example: 12345 explode: false in: path - name: userId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple responses: - "204": - description: Response body has no content + "201": + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceStopActionResponse' + description: Information of stoped instance security: - bearer: [] - summary: Delete existing user by id + summary: Stop compute instance / resource by its id tags: - - Users + - Instance Actions x-codeSamples: - lang: cURL - source: 'curl -X DELETE ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' + source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/stop"' - lang: cntb CLI - source: cntb delete user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - get: - description: Get attributes for a specific user. - operationId: retrieveUser + source: cntb stop instance 1234 + /v1/compute/instances/{instanceId}/actions/shutdown: + post: + description: Shutdown an compute instance / resource. This is similar to pressing + the power button on a physical machine. This will send an ACPI event for the + guest OS, which should then proceed to a clean shutdown. + operationId: shutdown parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -583,41 +547,44 @@ paths: schema: type: string style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - description: The identifier of the compute instance / resource to be started + in rescue mode. + example: 12345 explode: false in: path - name: userId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/FindUserResponse' - description: The response will be a JSON object and contains standard user - attributes. + $ref: '#/components/schemas/InstanceShutdownActionResponse' + description: Information of a shutdown instance security: - bearer: [] - summary: Get specific user by id + summary: Shutdown compute instance / resource by its id tags: - - Users + - Instance Actions x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' + source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/shutdown"' - lang: cntb CLI - source: cntb get user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - patch: - description: Update attributes of a user. You may only specify the attributes - you want to change. If an attribute is not set, it will retain its original - value. - operationId: updateUser + source: cntb shutdown instance 1234 + /v1/compute/instances/{instanceId}/actions/rescue: + post: + description: You can reboot your instance in rescue mode to resolve system issues. + Rescue system is Linux based and its booted instead of your regular operating + system. The disk containing your operating sytstem, software and your data + is already mounted for you to access and repair/modify files. After a reboot + your compute instance will boot your operating system. Please note that this + is for advanced users. + operationId: rescue parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -639,47 +606,72 @@ paths: schema: type: string style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - description: The identifier of the compute instance / resource to be started + in rescue mode. + example: 12345 explode: false in: path - name: userId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple requestBody: content: application/json: schema: - $ref: '#/components/schemas/UpdateUserRequest' + $ref: '#/components/schemas/InstancesActionsRescueRequest' required: true responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/UpdateUserResponse' - description: The response will be a JSON object and contains standard user - attributes. + $ref: '#/components/schemas/InstanceRescueActionResponse' + description: Information of rescued instance security: - bearer: [] - summary: Update specific user by id + summary: Rescue a compute instance / resource identified by its id tags: - - Users + - Instance Actions x-codeSamples: - lang: cURL - source: 'curl -X PATCH ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213'' -d ''{"enabled":true,"roles":[1,2,3]}''' + source: "curl -X POST \"https://api.contabo.com/v1/compute/instances/1234/actions/rescue\"\ + \ -H \"Authorization: Bearer ${ACCESS_TOKEN}\" -H \"x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31\"\ + \ -H \"x-trace-id: 123213\" -d '{\"sshKeys\": [1,2], \"rootPassword\": 12,\ + \ \"userData\": \"#cloud-config\n user: root\n ssh_pwauth: true\n disable_root:\ + \ false\n ssh_authorized_keys:\n - \n chpasswd:\n list:\n - root:\ + \ \n expire: False\n\"}'" - lang: cntb CLI - source: cntb update user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 --enabled --roles - 1 - /v1/users/{userId}/reset-password: + source: |- + cntb rescue instance 1234 --sshKeys "1,2" --rootPassword 12 --userData '#cloud-config + + + + + + + + + + + + + + + + user: root + ssh_pwauth: true + disable_root: false + ssh_authorized_keys: + - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL6Bja3wXjkpxkGrNkBqcb/WeRlWO33XWnKHS/Uf9lmH testKey' + /v1/compute/instances/{instanceId}/actions/resetPassword: post: - description: Send reset password email for a specific user - operationId: resetPassword + description: Reset password for a compute instance / resource referenced by + an id. This will reset the current password to the password that you provided + in the body of this request. + operationId: resetPasswordAction parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -701,43 +693,51 @@ paths: schema: type: string style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - description: The identifier of the compute instance / resource to be started + in rescue mode. + example: 12345 explode: false in: path - name: userId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple - - description: The redirect url used for resetting password - example: https://test.contabo.de - explode: true - in: query - name: redirectUrl - required: false - schema: - type: string - style: form + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/InstancesResetPasswordActionsRequest' + required: true responses: - "204": - description: Response body has no content + "201": + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceResetPasswordActionResponse' + description: Information of an instance password reset security: - bearer: [] - summary: Send reset password email + summary: Reset password for a compute instance / resource referenced by an id tags: - - Users + - Instance Actions x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/reset-password'' - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' - -H ''x-trace-id: 123213''' + source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/resetPassword" + -d ''{"sshKeys": [1,2], "rootPassword": 12, "userData": "''#cloud-config\nuser: + root\nssh_pwauth: true\ndisable_root: false\nssh_authorized_keys:\n - \nchpasswd:\n list:\n - + root: \n expire: False\n''"}''' - lang: cntb CLI - source: cntb resetPassword user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - /v1/users/{userId}/resend-email-verification: - post: - description: Resend email verification for a specific user - operationId: resendEmailVerification + source: "cntb resetPassword instance 1234 --sshKeys \"1,2\" --rootPassword\ + \ 12 --userData \"#cloud-config\n user: root\n ssh_pwauth: true\n disable_root:\ + \ false\n ssh_authorized_keys:\n - \n chpasswd:\n list:\n - root:\ + \ \n expire: False\n\"" + /v1/compute/instances: + get: + description: List and filter all instances in your account + operationId: retrieveInstancesList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -759,294 +759,184 @@ paths: schema: type: string style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - explode: false - in: path - name: userId - required: true + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page + required: false schema: - type: string - style: simple - - description: The redirect url used for email verification - example: https://test.contabo.de + format: int64 + type: integer + style: form + - description: Number of elements per page. + example: 10 explode: true in: query - name: redirectUrl + name: size required: false schema: - type: string + format: int64 + type: integer style: form - responses: - "204": - description: Response body has no content - security: - - bearer: [] - summary: Resend email verification - tags: - - Users - x-codeSamples: - - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/resend-email-verification'' - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' - -H ''x-trace-id: 123213''' - - lang: cntb CLI - source: cntb resendEmailVerification user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - /v1/users/client: - get: - description: Get idm client. - operationId: retrieveUserClient - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true + - description: Specify fields and ordering (ASC for ascending, DESC for descending) + in following format `field:ASC|DESC`. + example: name:asc + explode: true + in: query + name: orderBy + required: false + schema: + items: + type: string + type: array + style: form + - description: The name of the instance + example: vmd12345 + explode: true + in: query + name: name + required: false schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + style: form + - description: The display name of the instance + example: myTestInstance + explode: true + in: query + name: displayName required: false schema: type: string - style: simple - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/FindClientResponse' - description: The response will be a JSON object and contains standard client - attributes. - security: - - bearer: [] - summary: Get client - tags: - - Users - x-codeSamples: - - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/users/client'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - /v1/users/client/secret: - put: - description: Generate and get new client secret. - operationId: generateClientSecret - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true + style: form + - description: The data center of the instance + example: European Union (Germany) 1 + explode: true + in: query + name: dataCenter + required: false schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + style: form + - description: The Region of the instance + example: EU + explode: true + in: query + name: region required: false schema: type: string - style: simple - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/GenerateClientSecretResponse' - description: The response will be a JSON object and contains new client - secret. - security: - - bearer: [] - summary: Generate new client secret - tags: - - Users - x-codeSamples: - - lang: cURL - source: 'curl -X PUT ''https://api.contabo.com/v1/users/client/secret'' -H - "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' - -H ''x-trace-id: 123213''' - - lang: cntb CLI - source: cntb generateSecret user - /v1/users/is-password-set: - get: - description: Get info about idm user if the password is set. - operationId: retrieveUserIsPasswordSet - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id - required: false - schema: - type: string - style: simple - - description: The user ID for checking if password is set for him - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - explode: true - in: query - name: userId - required: false - schema: - type: string - style: form - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/FindUserIsPasswordSetResponse' - description: The response will be a JSON object and contains standard user - attributes. - security: - - bearer: [] - summary: Get user is password set status - tags: - - Internal - /v1/roles: - get: - description: List and filter all your roles. A role allows you to specify permission - to api endpoints and resources like compute. - operationId: retrieveRoleList - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id - required: false - schema: - type: string - style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false - schema: - format: int64 - type: integer style: form - - description: Number of elements per page. - example: 10 + - deprecated: true + description: The identifier of the instance (deprecated) + example: 100 explode: true in: query - name: size + name: instanceId required: false schema: format: int64 type: integer style: form - - description: Specify fields and ordering (ASC for ascending, DESC for descending) - in following format `field:ASC|DESC`. - example: name:asc + - description: Comma separated instances identifiers + example: 100, 101, 102 explode: true in: query - name: orderBy + name: instanceIds required: false schema: - items: - type: string - type: array + type: string style: form - - description: The name of the role - example: Web + - description: The status of the instance + example: provisioning,installing explode: true in: query - name: name + name: status required: false schema: + enum: + - provisioning + - uninstalled + - running + - stopped + - error + - installing + - unknown + - manual_provisioning + - product_not_available + - verification_required + - rescue + - pending_payment + - other type: string style: form - - description: The name of api - example: /v1/compute/instances + - description: Identifiers of Addons the instances have + example: 1044,827 explode: true in: query - name: apiName + name: addOnIds required: false schema: type: string style: form - - description: The name of the tag - example: Web + - description: Comma separated instance's category depending on Product Id + example: ssd, hdd, nvme explode: true in: query - name: tagName + name: productTypes required: false schema: type: string style: form - - description: The type of the tag. Can be either `default` or `custom` - example: custom + - description: Filter instances that have an ip config + example: true explode: true in: query - name: type + name: ipConfig required: false schema: - type: string + type: boolean style: form responses: "200": content: application/json: schema: - $ref: '#/components/schemas/ListRoleResponse' + $ref: '#/components/schemas/ListInstancesResponse' description: The response will be a JSON object and contains a paginated - list of roles. + list of instances. security: - bearer: [] - summary: List roles + summary: List instances tags: - - Roles + - Instances x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/roles'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' + source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb get roles + source: cntb get instances post: - description: Create a new role. In order to get a list availbale api enpoints - (apiName) and their actions please refer to the GET api-permissions endpoint. - For specifying `resources` please enter tag ids. For those to take effect - please assign them to a resource in the tag management api. - operationId: createRole + description: Create a new instance for your account with the provided parameters.
ProductIdProductDisk + Size
V45VPS 1 SSD400 GB SSD
V47VPS + 1 Storage800 GB SSD
V46VPS 1 + NVMe100 GB NVMe
V48VPS 2 SSD400 + GB SSD
V50VPS 2 Storage800 GB + SSD
V49VPS 2 NVMe200 GB NVMe
V51VPS + 3 SSD1200 GB SSD
V53VPS 3 Storage2400 + GB SSD
V52VPS 3 NVMe300 GB NVMe
V54VPS + 4 SSD1600 GB SSD
V56VPS 4 Storage3200 + GB SSD
V55VPS 4 NVMe400 GB NVMe
V57VPS + 5 SSD2000 GB SSD
V59VPS 5 Storage4000 + GB SSD
V58VPS 5 NVMe500 GB NVMe
V60VPS + 6 SSD2400 GB SSD
V62VPS 6 Storage4800 + GB SSD
V61VPS 6 NVMe600 GB NVMe
V8VDS + S180 GB NVMe
V9VDS M240 + GB NVMe
V10VDS L360 GB NVMe
V11VDS + XL480 GB NVMe
V16VDS XXL720 + GB NVMe
+ operationId: createInstance parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1072,37 +962,35 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CreateRoleRequest' + $ref: '#/components/schemas/CreateInstanceRequest' required: true responses: "201": content: application/json: schema: - $ref: '#/components/schemas/CreateRoleResponse' - description: The response will be a JSON object and contains standard role + $ref: '#/components/schemas/CreateInstanceResponse' + description: The response will be a JSON object and contains standard instance attributes. security: - bearer: [] - summary: Create a new role + summary: Create a new instance tags: - - Roles + - Instances x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/roles'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{"name":"infrastructure","permissions":{ - "apiName": "/v1/compute/instances", "actions": [ "CREATE", "READ" ], "resources": - [1111,2222] } }''' + source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances'' -H + "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: + 123213'' -d ''{"region": "EU", "productId": "V1", "imageId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", + "period": 1}''' - lang: cntb CLI - source: 'cntb create role --name "infrastructure" --permissions ''[{"apiName" - : "/v1/compute/instances", "actions": ["CREATE", "READ"], "resources": [1111, - 2222]}]''' - /v1/roles/{roleId}: - delete: - description: You can't delete a role if it is still assigned to a user. In such - cases please remove the role from the users. - operationId: deleteRole + source: create instance --period 1 --imageId "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" + --productId "V1" -r "EU" + /v1/compute/instances/{instanceId}: + get: + description: Get attributes values to a specific instance on your account. + operationId: retrieveInstance parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1124,34 +1012,40 @@ paths: schema: type: string style: simple - - description: The identifier of the role + - description: The identifier of the instance example: 12345 explode: false in: path - name: roleId + name: instanceId required: true schema: format: int64 type: integer style: simple responses: - "204": - description: Response body has no content + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/FindInstanceResponse' + description: The response will be a JSON object and contains standard instance + attributes. security: - bearer: [] - summary: Delete existing role by id + summary: Get specific instance by id tags: - - Roles + - Instances x-codeSamples: - lang: cURL - source: 'curl -X DELETE ''https://api.contabo.com/v1/roles/12345'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' + source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances/12345'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: + 123213''' - lang: cntb CLI - source: cntb delete role 12345 - get: - description: Get attributes of specific role. - operationId: retrieveRole + source: cntb get instance 12345 + patch: + description: Update specific instance by instanceId. + operationId: patchInstance parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1173,40 +1067,47 @@ paths: schema: type: string style: simple - - description: The identifier of the role + - description: The identifier of the instance example: 12345 explode: false in: path - name: roleId + name: instanceId required: true schema: format: int64 type: integer style: simple - responses: - "200": + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchInstanceRequest' + required: true + responses: + "200": content: application/json: schema: - $ref: '#/components/schemas/FindRoleResponse' - description: The response will be a JSON object and contains standard role - attributes. + $ref: '#/components/schemas/PatchInstanceResponse' + description: The response will be a JSON object and contains instanceId + and createdDate. security: - bearer: [] - summary: Get specific role by id + summary: Update specific instance tags: - - Roles + - Instances x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/roles/12345'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' + source: 'curl -X PATCH ''https://api.contabo.com/v1/compute/instances/12345'' + -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: + 123213" -d ''{"displayName": "VPS"}''' - lang: cntb CLI - source: cntb get role 12345 + source: cntb update instance 12345 --displayName "VPS" put: - description: Update attributes to your role. Attributes are optional. If not - set, the attributes will retain their original values. - operationId: updateRole + description: You can reinstall a specific instance with a new image and optionally + add ssh keys, a root password or cloud-init. + operationId: reinstallInstance parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1228,11 +1129,11 @@ paths: schema: type: string style: simple - - description: The identifier of the role + - description: The identifier of the instance example: 12345 explode: false in: path - name: roleId + name: instanceId required: true schema: format: int64 @@ -1242,37 +1143,35 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/UpdateRoleRequest' + $ref: '#/components/schemas/ReinstallInstanceRequest' required: true responses: "200": content: application/json: schema: - $ref: '#/components/schemas/UpdateRoleResponse' - description: The response will be a JSON object and contains standard role - attributes. + $ref: '#/components/schemas/ReinstallInstanceResponse' + description: The response will be a JSON object and contains instanceId + and createdDate. security: - bearer: [] - summary: Update specific role by id + summary: Reinstall specific instance tags: - - Roles + - Instances x-codeSamples: - lang: cURL - source: 'curl -X PATCH ''https://api.contabo.com/v1/roles/12345'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{"name":"infrastructure","permissions":[ - {"apiName": "/v1/compute/instances", "actions": ["READ"] }], "accessAllResources": - true }''' + source: 'curl -X PUT ''https://api.contabo.com/v1/compute/instances/12345'' + -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: + 123213" -d ''{"imageId": "a2c26e8f-84a5-4f3e-9c0e-b06511928cc0", "sshKeys": + [1,2], "rootPassword": 12}''' - lang: cntb CLI - source: 'cntb update role 12345 --name newName --permissions ''[{"apiName" - : "/v1/compute/instances", "actions": ["CREATE", "READ"]}]'' --accessAllResources' - /v1/roles/api-permissions: - get: - description: List all available API permissions. This list serves as a reference - for specifying roles. As endpoints differ in their possibilities not all actions - are available for each endpoint. - operationId: retrieveApiPermissionsList + source: cntb reinstall instance 12345 --imageId "a2c26e8f-84a5-4f3e-9c0e-b06511928cc0" + --sshKeys "1,2" --rootPassword 12 + /v1/compute/instances/{instanceId}/cancel: + post: + description: Your are free to cancel a previously created instance at any time. + operationId: cancelInstance parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1294,72 +1193,42 @@ paths: schema: type: string style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false - schema: - format: int64 - type: integer - style: form - - description: Number of elements per page. - example: 10 - explode: true - in: query - name: size - required: false + - description: The identifier of the instance + example: 12345 + explode: false + in: path + name: instanceId + required: true schema: format: int64 type: integer - style: form - - description: Specify fields and ordering (ASC for ascending, DESC for descending) - in following format `field:ASC|DESC`. - example: name:asc - explode: true - in: query - name: orderBy - required: false - schema: - items: - type: string - type: array - style: form - - description: The name of api - example: /v1/compute/instances - explode: true - in: query - name: apiName - required: false - schema: - type: string - style: form + style: simple responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/ListApiPermissionResponse' - description: The response will be a JSON object and contains a paginated - list of API permissions. + $ref: '#/components/schemas/CancelInstanceResponse' + description: The response will be a JSON object and contains standard custom + image attributes security: - bearer: [] - summary: List of API permissions + summary: Cancel specific instance by id tags: - - Roles + - Instances x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/api-permissions'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' + source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/cancel'' + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' + -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb get permissions - /v1/users/{userId}/object-storages/credentials: - get: - description: Get list of S3 compatible object storage credentials for accessing - it via S3 compatible tools like `aws` cli. - operationId: listObjectStorageCredentials + source: cntb cancel instance 12345 + /v1/compute/instances/{instanceId}/upgrade: + post: + description: In order to enhance your instance with additional features you + can purchase add-ons. Currently only firewalling and private network addon + is allowed. + operationId: upgradeInstance parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1381,12 +1250,66 @@ paths: schema: type: string style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - description: The identifier of the instance + example: 12345 explode: false in: path - name: userId + name: instanceId + required: true + schema: + format: int64 + type: integer + style: simple + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpgradeInstanceRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/PatchInstanceResponse' + description: The response will be a JSON object and contains standard instance + attributes. + security: + - bearer: [] + summary: Upgrading instance capabilities + tags: + - Instances + x-codeSamples: + - lang: cURL + source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/upgrade'' + -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: + 123213" -d ''{ "privateNetworking": {} }''' + - lang: cntb CLI + source: cntb upgrade instance 12345 --privateNetworking=true + /v1/compute/instances/actions/audits: + get: + description: List and filters the history about your actions your triggered + via the API. + operationId: retrieveInstancesActionsAuditsList + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false schema: type: string style: simple @@ -1422,32 +1345,52 @@ paths: type: string type: array style: form - - description: The identifier of the S3 object storage - example: d8417276-d2d9-43a9-a0a8-9a6fa6060246 + - description: The identifier of the instancesActions. + example: 12345 explode: true in: query - name: objectStorageId + name: instanceId + required: false + schema: + format: int64 + type: integer + style: form + - description: The requestId of the API call which led to the change. + example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 + explode: true + in: query + name: requestId required: false schema: type: string style: form - - description: 'Filter for Object Storage by regions. Available regions: Asia - (Singapore), European Union (Germany), United States (Central)' - example: Asia (Singapore) + - description: changedBy of the user which led to the change. + example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 explode: true in: query - name: regionName + name: changedBy required: false schema: type: string style: form - - description: Filter for Object Storage by his displayName. - example: Object Storage EU 420 + - description: Start of search time range. + example: 2021-06-02 explode: true in: query - name: displayName + name: startDate + required: false + schema: + format: date + type: string + style: form + - description: End of search time range. + example: 2021-06-02 + explode: true + in: query + name: endDate required: false schema: + format: date type: string style: form responses: @@ -1455,176 +1398,25 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListCredentialResponse' - description: The response will be an array of JSON objects that contains - S3 credentials. + $ref: '#/components/schemas/ListInstancesActionsAuditResponse' + description: The response will be a JSON object and contains a paginated + list of action audits triggered via the API. security: - bearer: [] - summary: Get list of S3 compatible object storage credentials for user. - tags: - - Users - x-codeSamples: - - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/object-storages/credentials'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' - - lang: cntb CLI - source: cntb get user-credentials 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - /v1/users/{userId}/object-storages/{objectStorageId}/credentials/{credentialId}: - get: - description: Get S3 compatible object storage credentials for accessing it via - S3 compatible tools like `aws` cli. - operationId: getObjectStorageCredentials - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id - required: false - schema: - type: string - style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - explode: false - in: path - name: userId - required: true - schema: - type: string - style: simple - - description: The identifier of the S3 object storage - example: d8417276-d2d9-43a9-a0a8-9a6fa6060246 - explode: false - in: path - name: objectStorageId - required: true - schema: - type: string - style: simple - - description: The ID of the object storage credential - example: 12345 - explode: false - in: path - name: credentialId - required: true - schema: - format: int64 - type: integer - style: simple - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/FindCredentialResponse' - description: The response will be a JSON object and contains S3 credentials. - security: - - bearer: [] - summary: Get S3 compatible object storage credentials. - tags: - - Users - x-codeSamples: - - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/object-storages/6641ae21-e45d-4e03-8e70-661067152d1d/credentials/12345'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' - - lang: cntb CLI - source: cntb get user-credentials 6cdf5968-f9fe-4192-97c2-f349e813c5e8 6641ae21-e45d-4e03-8e70-661067152d1d - 12345 - patch: - description: Regenerates secret key of specified user for the a specific S3 - compatible object storages. - operationId: regenerateObjectStorageCredentials - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id - required: false - schema: - type: string - style: simple - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - explode: false - in: path - name: userId - required: true - schema: - type: string - style: simple - - description: The identifier of the S3 object storage - example: d8417276-d2d9-43a9-a0a8-9a6fa6060246 - explode: false - in: path - name: objectStorageId - required: true - schema: - type: string - style: simple - - description: The ID of the object storage credential - example: 12345 - explode: false - in: path - name: credentialId - required: true - schema: - format: int64 - type: integer - style: simple - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/FindCredentialResponse' - description: The response will be a JSON object and contains object storage - S3 credentials. - security: - - bearer: [] - summary: Regenerates secret key of specified user for the S3 compatible object - storages. + summary: List history about your actions (audit) triggered via the API tags: - - Users + - Instance Actions Audits x-codeSamples: - lang: cURL - source: 'curl -X PATCH ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/object-storages/6641ae21-e45d-4e03-8e70-661067152d1d/credentials/12345'' - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' - -H ''x-trace-id: 123213''' + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/actions/audits"' - lang: cntb CLI - source: cntb regenerate user-credentials 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - 6641ae21-e45d-4e03-8e70-661067152d1d 12345 - /v1/users/audits: + source: cntb history instancesActions + /v1/compute/instances/audits: get: - description: List and filter the history about your users. - operationId: retrieveUserAuditsList + description: List and filters the history about your custom images. + operationId: retrieveInstancesAuditsList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1678,14 +1470,15 @@ paths: type: string type: array style: form - - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - description: The identifier of the instances. + example: 12345 explode: true in: query - name: userId + name: instanceId required: false schema: - type: string + format: int64 + type: integer style: form - description: The requestId of the API call which led to the change. example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 @@ -1706,7 +1499,7 @@ paths: type: string style: form - description: Start of search time range. - example: 2021-01-01 + example: 2021-06-02 explode: true in: query name: startDate @@ -1716,7 +1509,7 @@ paths: type: string style: form - description: End of search time range. - example: 2021-01-01 + example: 2021-06-02 explode: true in: query name: endDate @@ -1730,25 +1523,26 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListUserAuditResponse' + $ref: '#/components/schemas/ListInstancesAuditResponse' description: The response will be a JSON object and contains a paginated - list of users audits. + list of instances audits triggered via the API. security: - bearer: [] - summary: List history about your users (audit) + summary: List history about your custom images (audit) tags: - - Users Audits + - Instances Audits x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/users/audits'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31''' + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/audits"' - lang: cntb CLI - source: cntb history users - /v1/roles/audits: + source: cntb history instances + /v1/compute/images: get: - description: List and filter the history about your roles. - operationId: retrieveRoleAuditsList + description: List and filter all available standard images provided by [Contabo](https://contabo.com) + and your uploaded custom images. + operationId: retrieveImageList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1802,78 +1596,53 @@ paths: type: string type: array style: form - - description: The identifier of the role. - example: "12345" - explode: true - in: query - name: roleId - required: false - schema: - format: int64 - type: integer - style: form - - description: The requestId of the API call which led to the change. - example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 - explode: true - in: query - name: requestId - required: false - schema: - type: string - style: form - - description: changedBy of the user which led to the change. - example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 - explode: true - in: query - name: changedBy - required: false - schema: - type: string - style: form - - description: Start of search time range. - example: 2021-01-01 + - description: The name of the image + example: Ubuntu explode: true in: query - name: startDate + name: name required: false schema: - format: date type: string style: form - - description: End of search time range. - example: 2021-01-01 + - description: Flag indicating that image is either a standard (true) or a custom + image (false) + example: true explode: true in: query - name: endDate + name: standardImage required: false schema: - format: date - type: string + type: boolean style: form responses: "200": content: application/json: schema: - $ref: '#/components/schemas/ListRoleAuditResponse' + $ref: '#/components/schemas/ListImageResponse' description: The response will be a JSON object and contains a paginated - list of roles audits. + list of images. security: - bearer: [] - summary: List history about your roles (audit) + summary: List available standard and custom images tags: - - Roles Audits + - Images x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/roles/audits'' -H ''Content-Type: + source: 'curl -X GET ''https://api.contabo.com/v1/compute/images'' -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31''' + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb history roles - /v1/object-storages: - get: - description: List and filter all object storages in your account - operationId: retrieveObjectStorageList + source: cntb get images + post: + description: In order to provide a custom image please specify an URL from where + the image can be directly downloaded. A custom image must be in either `.iso` + or `.qcow2` format. Other formats will be rejected. Please note that downloading + can take a while depending on network speed resp. bandwidth and size of image. + You can check the status by retrieving information about the image via a GET + request. Download will be rejected if you have exceeded your limits. + operationId: createCustomImage parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -1895,92 +1664,153 @@ paths: schema: type: string style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCustomImageRequest' + required: true + responses: + "201": + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCustomImageResponse' + description: The response will be a JSON object and contains standard custom + image attributes + "415": + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCustomImageFailResponse' + description: The response will be an error in case the provided image URL + is not in .qcow2 or .iso format + security: + - bearer: [] + summary: Provide a custom image + tags: + - Images + x-codeSamples: + - lang: cURL + source: 'curl -X POST ''https://api.contabo.com/v1/compute/images'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{"name": + "Ubuntu Custom Image", "description": "Ubuntu Server 20.04.2 LTS", "url": + "https://example.com/image.qcow2", "osType": "Linux", "version": "20.04.2"}''' + - lang: cntb CLI + source: cntb create image --name 'Ubuntu Custom Image' --description 'Ubuntu + Server 20.04.2 LTS' --url https://example.com/image.qcow2 --osType Linux + --version 20.04.2 + /v1/compute/images/{imageId}: + delete: + description: Your are free to delete a previously uploaded custom images at + any time + operationId: deleteImage + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true schema: - format: int64 - type: integer - style: form - - description: Number of elements per page. - example: 10 - explode: true - in: query - name: size + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id required: false schema: - format: int64 - type: integer - style: form - - description: Specify fields and ordering (ASC for ascending, DESC for descending) - in following format `field:ASC|DESC`. - example: name:asc - explode: true - in: query - name: orderBy - required: false + type: string + style: simple + - description: The identifier of the image + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + explode: false + in: path + name: imageId + required: true schema: - items: - type: string - type: array - style: form - - description: Filter for Object Storage locations. - example: European Union (Germany) 2 - explode: true - in: query - name: dataCenterName - required: false + type: string + style: simple + responses: + "204": + description: Response body has no content + security: + - bearer: [] + summary: Delete an uploaded custom image by its id + tags: + - Images + x-codeSamples: + - lang: cURL + source: 'curl -X DELETE ''https://api.contabo.com/v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' + - lang: cntb CLI + source: cntb delete image 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + get: + description: Get details about a specific image. This could be either a standard + or custom image. In case of an custom image you can also check the download + status + operationId: retrieveImage + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true schema: - minLength: 1 + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - style: form - - description: Filter for Object Storage S3 tenantId. - example: 2cd2e5e1444a41b0bed16c6410ecaa84 - explode: true - in: query - name: s3TenantId + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id required: false schema: type: string - style: form - - description: 'Filter for Object Storage by regions. Available regions: EU, - US-central, SIN' - example: EU - explode: true - in: query - name: region - required: false + style: simple + - description: The identifier of the image + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + explode: false + in: path + name: imageId + required: true schema: type: string - style: form + style: simple responses: "200": content: application/json: schema: - $ref: '#/components/schemas/ListObjectStorageResponse' - description: The response will be a JSON object and contains a paginated - list of object storages. + $ref: '#/components/schemas/FindImageResponse' + description: The response will be a JSON object and contains standard custom + image attributes security: - bearer: [] - summary: List all your object storages + summary: Get details about a specific image by its id tags: - - Object Storages + - Images x-codeSamples: - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages"' + source: 'curl -X GET ''https://api.contabo.com/v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' - lang: cntb CLI - source: cntb get objectStorages - post: - description: Create / purchase a new object storage in your account. Please - note that you can only buy one object storage per location. You can actually - increase the object storage space via `POST` to `/v1/object-storages/{objectStorageId}/resize` - operationId: createObjectStorage + source: cntb get image 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + patch: + description: Update name of the custom image + operationId: updateImage parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2002,40 +1832,49 @@ paths: schema: type: string style: simple + - description: The identifier of the image + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + explode: false + in: path + name: imageId + required: true + schema: + type: string + style: simple requestBody: content: application/json: schema: - $ref: '#/components/schemas/CreateObjectStorageRequest' + $ref: '#/components/schemas/UpdateCustomImageRequest' required: true responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/CreateObjectStorageResponse' - description: The response will be a JSON object and contains standard object - storage attributes. + $ref: '#/components/schemas/UpdateCustomImageResponse' + description: The response will be a JSON object and contains standard custom + image attributes security: - bearer: [] - summary: Create a new object storage + summary: Update custom image name by its id tags: - - Object Storages + - Images x-codeSamples: - lang: cURL - source: 'curl -X POST "https://api.contabo.com/v1/object-storages" -H "accept: - application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: 123213" -H "Content-Type: - application/json" -d ''{ "displayName": "Object storage EU 1", "region": - "EU", "autoScaling": { "state": "enabled", "sizeLimitTB": 1 }, "totalPurchasedSpaceTB": - 1 }''' + source: 'curl -X PATCH ''https://api.contabo.com/v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213'' -d ''{"name": "Ubuntu Custom Image"}''' - lang: cntb CLI - source: cntb create objectStorage --displayName "Object storage EU 1" --region - "EU" --totalPurchasedSpaceTB 1 --scalingState=enabled --scalingLimitTB 1 - /v1/data-centers: + source: cntb update image 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d --name 'Ubuntu + Custom Image' + /v1/compute/images/stats: get: - description: List all data centers and their corresponding regions. - operationId: retrieveDataCenterList + description: List statistics regarding the customer's custom images such as + the number of custom images uploaded, used disk space, free available disk + space and total available disk space + operationId: retrieveCustomImagesStats parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2057,9 +1896,66 @@ paths: schema: type: string style: simple - - description: Number of page to be fetched. - example: 1 - explode: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/CustomImagesStatsResponse' + description: The response will be a JSON object and contains the custom + images count, the total available disk space, the used disk space and + the free disk space. + security: + - bearer: [] + summary: List statistics regarding the customer's custom images + tags: + - Images + x-codeSamples: + - lang: cURL + source: 'curl -X GET ''https://api.contabo.com/v1/compute/images/stats'' -H + ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' + - lang: cntb CLI + source: cntb get images stats + /v1/compute/instances/{instanceId}/snapshots: + get: + description: List and filter all your snapshots for a specific instance + operationId: retrieveSnapshotList + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: + type: string + style: simple + - description: The identifier of the instance + example: 12345 + explode: false + in: path + name: instanceId + required: true + schema: + format: int64 + type: integer + style: simple + - description: Number of page to be fetched. + example: 1 + explode: true in: query name: page required: false @@ -2089,44 +1985,13 @@ paths: type: string type: array style: form - - description: Filter as match for data centers. - example: EU1 - explode: true - in: query - name: slug - required: false - schema: - minLength: 1 - type: string - style: form - - description: Filter for Object Storages regions. - example: European Union (Germany) 1 + - description: Filter as substring match for snapshots names. + example: Snapshot.Server explode: true in: query name: name required: false schema: - minLength: 1 - type: string - style: form - - description: Filter for Object Storage region names. - example: European Union (Germany) - explode: true - in: query - name: regionName - required: false - schema: - minLength: 1 - type: string - style: form - - description: Filter for Object Storage region slugs. - example: EU - explode: true - in: query - name: regionSlug - required: false - schema: - minLength: 1 type: string style: form responses: @@ -2134,24 +1999,25 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListDataCenterResponse' + $ref: '#/components/schemas/ListSnapshotResponse' description: The response will be a JSON object and contains a paginated - list of data centers. + list of snapshots attributes security: - bearer: [] - summary: List data centers + summary: List snapshots tags: - - Object Storages + - Snapshots x-codeSamples: - lang: cURL - source: 'curl -X GET -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: 123213" "https://api.contabo.com/v1/data-centers"' + source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances/12345/snapshots'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' - lang: cntb CLI - source: cntb get datacenters - /v1/object-storages/{objectStorageId}: - get: - description: Get data for a specific object storage on your account. - operationId: retrieveObjectStorage + source: cntb get snapshots 12345 + post: + description: Create a new snapshot for instance, with name and description attributes + operationId: createSnapshot parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2173,39 +2039,48 @@ paths: schema: type: string style: simple - - description: The identifier of the object storage. - example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 + - description: The identifier of the instance + example: 12345 explode: false in: path - name: objectStorageId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateSnapshotRequest' + required: true responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/FindObjectStorageResponse' - description: The response will be a JSON object and contains standard object - storage attributes. + $ref: '#/components/schemas/CreateSnapshotResponse' + description: The response will be a JSON object and contains standard snapshot + attributes security: - bearer: [] - summary: Get specific object storage by its id + summary: Create a new instance snapshot tags: - - Object Storages + - Snapshots x-codeSamples: - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc"' + source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/snapshots'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213'' -d ''{"name":"Snapshot-Server","description":"Snapshot-Description"}''' - lang: cntb CLI - source: cntb get objectStorage ea639fc6-9aae-4d71-af8b-046dda87a9cc - patch: - description: Modifies the display name of object storage. Display name must - be unique. - operationId: updateObjectStorage + source: cntb create snapshot 12345 --name 'Snapshot-Server' --description + 'Snapshot-Description' + /v1/compute/instances/{instanceId}/snapshots/{snapshotId}: + delete: + description: Delete existing instance snapshot by id + operationId: deleteSnapshot parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2227,49 +2102,44 @@ paths: schema: type: string style: simple - - description: The identifier of the object storage. - example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 + - description: The identifier of the instance + example: 12345 explode: false in: path - name: objectStorageId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchObjectStorageRequest' + - description: The identifier of the snapshot + example: snap1628603855 + explode: false + in: path + name: snapshotId required: true + schema: + type: string + style: simple responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/CancelObjectStorageResponse' - description: The response will be a JSON object and contains the object - storage with updated display name. + "204": + description: Response body has no content security: - bearer: [] - summary: Modifies the display name of object storage + summary: Delete existing snapshot by id tags: - - Object Storages + - Snapshots x-codeSamples: - lang: cURL - source: 'curl -X PATCH "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc" - -H "accept: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: - 123213" -H "Content-Type: application/json" -d ''{ "displayName": "Object - storage EU 2"}''' + source: 'curl -X DELETE ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' - lang: cntb CLI - source: cntb update objectStorage --displayName "Object storage EU 1" - /v1/object-storages/{objectStorageId}/resize: - post: - description: Upgrade object storage size. You can also adjust the autoscaling - settings for your object storage. Autoscaling allows you to automatically - purchase storage capacity on a monthly basis up to the specified limit. - operationId: upgradeObjectStorage + source: cntb delete snapshot 12345 snap1628603855 + get: + description: Get all attributes for a specific snapshot + operationId: retrieveSnapshot parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2291,50 +2161,51 @@ paths: schema: type: string style: simple - - description: The identifier of the object storage. - example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 + - description: The identifier of the instance + example: 12345 explode: false in: path - name: objectStorageId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpgradeObjectStorageRequest' + - description: The identifier of the snapshot + example: snap1628603855 + explode: false + in: path + name: snapshotId required: true + schema: + type: string + style: simple responses: "200": content: application/json: schema: - $ref: '#/components/schemas/UpgradeObjectStorageResponse' - description: The response will be a JSON object and contains standard object - storage attributes. + $ref: '#/components/schemas/FindSnapshotResponse' + description: The response will be a JSON object and contains standard snapshot + attributes security: - bearer: [] - summary: Upgrade object storage size resp. update autoscaling settings. + summary: Retrieve a specific snapshot by id tags: - - Object Storages + - Snapshots x-codeSamples: - lang: cURL - source: 'curl -X POST -H "accept: application/json" -H "Content-Type: application/json" - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" - -H "x-trace-id: 123213" -d ''{ "autoScaling": { "state": "enabled", "sizeLimitTB": - 6 }, "totalPurchasedSpaceTB": 8 }'' "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc/resize"' - - lang: cntb CLI - source: cntb resize objectStorage ea639fc6-9aae-4d71-af8b-046dda87a9cc --totalPurchasedSpaceTB - 8 --scalingLimitTB 6 --scalingState="enabled" - /v1/object-storages/{objectStorageId}/stats: - get: - description: List usage statistics about the specified object storage such as - the number of objects uploaded / created, used object storage space. Please - note that the usage statistics are updated regularly and are not live usage - statistics. - operationId: retrieveObjectStoragesStats + source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' + - lang: cntb CLI + source: cntb get snapshot 12345 snap1628603855 + patch: + description: Update attributes of a snapshot. You may only specify the attributes + you want to change. If an attribute is not set, it will retain its original + value. + operationId: updateSnapshot parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2356,41 +2227,58 @@ paths: schema: type: string style: simple - - description: The identifier of the object storage. - example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 + - description: The identifier of the instance + example: 12345 explode: false in: path - name: objectStorageId + name: instanceId + required: true + schema: + format: int64 + type: integer + style: simple + - description: The identifier of the snapshot + example: snap1628603855 + explode: false + in: path + name: snapshotId required: true schema: type: string style: simple + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateSnapshotRequest' + required: true responses: "200": content: application/json: schema: - $ref: '#/components/schemas/ObjectStoragesStatsResponse' - description: The response will be a JSON object and contains the object - storages count the current object storages and give the current quota - maximum. + $ref: '#/components/schemas/UpdateSnapshotResponse' + description: The response will be a JSON object and contains standard snapshot + attributes security: - bearer: [] - summary: List usage statistics about the specified object storage + summary: Update specific snapshot by id tags: - - Object Storages + - Snapshots x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc/stats'' - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' - -H ''x-trace-id: 123213''' + source: 'curl -X PATCH ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213'' -d ''{"name":"Snapshot"}''' - lang: cntb CLI - source: cntb stats objectStorage 1f771979-1c0f-44ab-ab5b-2c3752731b45 - /v1/object-storages/{objectStorageId}/cancel: - patch: - description: Cancels the specified object storage at the next possible date. - Please be aware of your contract periods. - operationId: CancelObjectStorage + source: cntb update snapshot 12345 snap1628603855 --name 'Snapshot' + /v1/compute/instances/{instanceId}/snapshots/{snapshotId}/rollback: + post: + description: Rollback instance to a specific snapshot. The snapshot must be + the latest one in order to be able to restore it, otherwise you will receive + an error informing you that the snapshot is not the latest + operationId: rollbackSnapshot parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2412,56 +2300,22 @@ paths: schema: type: string style: simple - - description: The identifier of the object storage. - example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 + - description: The identifier of the instance + example: 12345 explode: false in: path - name: objectStorageId + name: instanceId required: true schema: - type: string + format: int64 + type: integer style: simple - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/CancelObjectStorageResponse' - description: The response will be a JSON object and contains the objectstorageId - and cancel date. - security: - - bearer: [] - summary: Cancels the specified object storage at the next possible date - tags: - - Object Storages - x-codeSamples: - - lang: cURL - source: 'curl -X PATCH -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc/cancel"' - - lang: cntb CLI - source: cntb cancel objectStorage 1f771979-1c0f-44ab-ab5b-2c3752731b45 - /v1/create-ticket: - post: - description: Create a new support ticket. - operationId: createTicket - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' + - description: The identifier of the snapshot + example: snap1628603855 explode: false - in: header - name: x-request-id + in: path + name: snapshotId required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id - required: false schema: type: string style: simple @@ -2469,31 +2323,32 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CreateTicketRequest' + $ref: '#/components/schemas/RollbackSnapshotRequest' required: true responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/CreateTicketResponse' - description: The response will be a JSON object and contains standard support - ticket attributes. + $ref: '#/components/schemas/RollbackSnapshotResponse' + description: The response will be a JSON object and contains standard snapshot + attributes security: - bearer: [] - summary: Create a new support ticket + summary: Revert the instance to a particular snapshot based on its identifier tags: - - Internal + - Snapshots x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/create-ticket'' -H "Content-Type: - application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: 123213'' -d ''{"subject": - "Subject", "note": "Note"}''' - /v1/object-storages/audits: + source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855/rollback'' + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' + -H ''x-trace-id: 123213''' + - lang: cntb CLI + source: cntb rollback snapshot 12345 snap1628603855 + /v1/compute/images/audits: get: - description: List and filters the history about your object storages. - operationId: retrieveObjectStorageAuditsList + description: List and filters the history about your custom images. + operationId: retrieveImageAuditsList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2547,11 +2402,11 @@ paths: type: string type: array style: form - - description: The identifier of the object storage. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - description: The identifier of the image. + example: e443eab5-647a-4bc3-b4f9-16f5a281224d explode: true in: query - name: objectStorageId + name: imageId required: false schema: type: string @@ -2565,7 +2420,7 @@ paths: schema: type: string style: form - - description: changedBy of the user which led to the change. + - description: UserId of the user which led to the change. example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 explode: true in: query @@ -2575,7 +2430,7 @@ paths: type: string style: form - description: Start of search time range. - example: 2021-01-01 + example: 2021-06-02 explode: true in: query name: startDate @@ -2585,7 +2440,7 @@ paths: type: string style: form - description: End of search time range. - example: 2021-01-01 + example: 2021-06-02 explode: true in: query name: endDate @@ -2599,25 +2454,26 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListObjectStorageAuditResponse' + $ref: '#/components/schemas/ImageAuditResponse' description: The response will be a JSON object and contains a paginated - list of object storage audits. + list of custom images audits. security: - bearer: [] - summary: List history about your object storages (audit) + summary: List history about your custom images (audit) tags: - - Object Storages Audits + - Images Audits x-codeSamples: - lang: cURL source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages/audits"' + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/images/audits"' - lang: cntb CLI - source: cntb history objectStorages - /v1/tags: + source: cntb history images + /v1/compute/snapshots/audits: get: - description: List and filter all tags in your account - operationId: retrieveTagList + description: List and filters the history about your snapshots your triggered + via the API. + operationId: retrieveSnapshotsAuditsList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2671,15 +2527,61 @@ paths: type: string type: array style: form - - description: Filter as substring match for tag names. Tags may contain letters, - numbers, colons, dashes, and underscores. There is a limit of 255 characters - per tag. - example: web + - description: The identifier of the instance + example: 12345 explode: true in: query - name: name + name: instanceId + required: false + schema: + format: int64 + type: integer + style: form + - description: The identifier of the snapshot + example: snap1628603855 + explode: true + in: query + name: snapshotId + required: false + schema: + type: string + style: form + - description: The requestId of the API call which led to the change + example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 + explode: true + in: query + name: requestId + required: false + schema: + type: string + style: form + - description: changedBy of the user which led to the change + example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 + explode: true + in: query + name: changedBy + required: false + schema: + type: string + style: form + - description: Start of search time range. + example: 2021-06-02 + explode: true + in: query + name: startDate + required: false + schema: + format: date + type: string + style: form + - description: End of search time range. + example: 2021-06-02 + explode: true + in: query + name: endDate required: false schema: + format: date type: string style: form responses: @@ -2687,25 +2589,25 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListTagResponse' + $ref: '#/components/schemas/ListSnapshotsAuditResponse' description: The response will be a JSON object and contains a paginated - list of tags. + list of snapshots audits triggered via the API. security: - bearer: [] - summary: List tags + summary: List history about your snapshots (audit) triggered via the API tags: - - Tags + - Snapshots Audits x-codeSamples: - lang: cURL source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags"' + -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/snapshots/audits"' - lang: cntb CLI - source: cntb get tags - post: - description: Create a new tag in your account with attribute name and optional - attribute color. - operationId: createTag + source: cntb history snapshots + /v1/object-storages: + get: + description: List and filter all object storages in your account + operationId: retrieveObjectStorageList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2727,141 +2629,92 @@ paths: schema: type: string style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateTagRequest' - required: true - responses: - "201": - content: - application/json: - schema: - $ref: '#/components/schemas/CreateTagResponse' - description: The response will be a JSON object and contains standard tag - attributes. - security: - - bearer: [] - summary: Create a new tag - tags: - - Tags - x-codeSamples: - - lang: cURL - source: 'curl -X POST "https://api.contabo.com/v1/tags" -H "accept: application/json" - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: - 123213" -H "Content-Type: application/json" -d ''{"name":"Web-Server","color":"#0A78C3"}''' - - lang: cntb CLI - source: cntb create tag --name "Web-Server" --color "#0A78C3" - /v1/tags/{tagId}: - delete: - description: Your tag can be deleted if it is not assigned to any resource on - your account. Check tag assigments before deleting tag. - operationId: deleteTag - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page required: false schema: - type: string - style: simple - - description: The identifier of the tag - example: 12345 - explode: false - in: path - name: tagId - required: true + format: int64 + type: integer + style: form + - description: Number of elements per page. + example: 10 + explode: true + in: query + name: size + required: false schema: format: int64 type: integer - style: simple - responses: - "204": - description: Response body has no content - security: - - bearer: [] - summary: Delete existing tag by id - tags: - - Tags - x-codeSamples: - - lang: cURL - source: 'curl -X DELETE -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345"' - - lang: cntb CLI - source: cntb delete tag 12345 - get: - description: Get attributes values to a specific tag on your account. - operationId: retrieveTag - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true + style: form + - description: Specify fields and ordering (ASC for ascending, DESC for descending) + in following format `field:ASC|DESC`. + example: name:asc + explode: true + in: query + name: orderBy + required: false schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + items: + type: string + type: array + style: form + - description: Filter for Object Storage locations. + example: European Union (Germany) 2 + explode: true + in: query + name: dataCenterName + required: false + schema: + minLength: 1 type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + style: form + - description: Filter for Object Storage S3 tenantId. + example: 2cd2e5e1444a41b0bed16c6410ecaa84 + explode: true + in: query + name: s3TenantId required: false schema: type: string - style: simple - - description: The identifier of the tag - example: 12345 - explode: false - in: path - name: tagId - required: true + style: form + - description: 'Filter for Object Storage by regions. Available regions: EU, + US-central, SIN' + example: EU + explode: true + in: query + name: region + required: false schema: - format: int64 - type: integer - style: simple + type: string + style: form responses: "200": content: application/json: schema: - $ref: '#/components/schemas/FindTagResponse' - description: The response will be a JSON object and contains standard tag - attributes. + $ref: '#/components/schemas/ListObjectStorageResponse' + description: The response will be a JSON object and contains a paginated + list of object storages. security: - bearer: [] - summary: Get specific tag by id + summary: List all your object storages tags: - - Tags + - Object Storages x-codeSamples: - lang: cURL source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345"' + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages"' - lang: cntb CLI - source: cntb get tag 12345 - patch: - description: Update attributes to your tag. Attributes are optional. If not - set, the attributes will retain their original values. - operationId: updateTag + source: cntb get objectStorages + post: + description: Create / purchase a new object storage in your account. Please + note that you can only buy one object storage per location. You can actually + increase the object storage space via `POST` to `/v1/object-storages/{objectStorageId}/resize` + operationId: createObjectStorage parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2883,46 +2736,40 @@ paths: schema: type: string style: simple - - description: The identifier of the tag - example: 12345 - explode: false - in: path - name: tagId - required: true - schema: - format: int64 - type: integer - style: simple requestBody: content: application/json: schema: - $ref: '#/components/schemas/UpdateTagRequest' + $ref: '#/components/schemas/CreateObjectStorageRequest' required: true responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/UpdateTagResponse' - description: The response will be a JSON object and contains standard tag - attributes. + $ref: '#/components/schemas/CreateObjectStorageResponse' + description: The response will be a JSON object and contains standard object + storage attributes. security: - bearer: [] - summary: Update specific tag by id + summary: Create a new object storage tags: - - Tags + - Object Storages x-codeSamples: - lang: cURL - source: 'curl -X PATCH -H "accept: application/json" -H "Content-Type: application/json" - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" -d ''{"name": "Updated-Web-Server"}'' "https://api.contabo.com/v1/tags/12345"' + source: 'curl -X POST "https://api.contabo.com/v1/object-storages" -H "accept: + application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: 123213" -H "Content-Type: + application/json" -d ''{ "displayName": "Object storage EU 1", "region": + "EU", "autoScaling": { "state": "enabled", "sizeLimitTB": 1 }, "totalPurchasedSpaceTB": + 1 }''' - lang: cntb CLI - source: cntb update tag 12345 --name "Updated-Web-Server" - /v1/tags/{tagId}/assignments: + source: cntb create objectStorage --displayName "Object storage EU 1" --region + "EU" --totalPurchasedSpaceTB 1 --scalingState=enabled --scalingLimitTB 1 + /v1/data-centers: get: - description: List and filter all existing assignments for a tag in your account - operationId: retrieveAssignmentList + description: List all data centers and their corresponding regions. + operationId: retrieveDataCenterList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -2944,16 +2791,6 @@ paths: schema: type: string style: simple - - description: The identifier of the tag. - example: "12345" - explode: false - in: path - name: tagId - required: true - schema: - format: int64 - type: integer - style: simple - description: Number of page to be fetched. example: 1 explode: true @@ -2986,42 +2823,69 @@ paths: type: string type: array style: form - - description: Filter as substring match for assignment resource type. Resource - type is one of `instance|image|object-storage`. - example: instance + - description: Filter as match for data centers. + example: EU1 explode: true in: query - name: resourceType + name: slug required: false schema: + minLength: 1 type: string style: form - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/ListAssignmentResponse' - description: The response will be a JSON object and contains a paginated - list of tag assignments. - security: - - bearer: [] - summary: List tag assignments - tags: - - Tag Assignments - x-codeSamples: - - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345/assignments"' + - description: Filter for Object Storages regions. + example: European Union (Germany) 1 + explode: true + in: query + name: name + required: false + schema: + minLength: 1 + type: string + style: form + - description: Filter for Object Storage region names. + example: European Union (Germany) + explode: true + in: query + name: regionName + required: false + schema: + minLength: 1 + type: string + style: form + - description: Filter for Object Storage region slugs. + example: EU + explode: true + in: query + name: regionSlug + required: false + schema: + minLength: 1 + type: string + style: form + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListDataCenterResponse' + description: The response will be a JSON object and contains a paginated + list of data centers. + security: + - bearer: [] + summary: List data centers + tags: + - Object Storages + x-codeSamples: + - lang: cURL + source: 'curl -X GET -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: 123213" "https://api.contabo.com/v1/data-centers"' - lang: cntb CLI - source: cntb get tagAssignments 12345 - /v1/tags/{tagId}/assignments/{resourceType}/{resourceId}: - delete: - description: Tag assignment will be removed from the specified resource. If - this tag is being used for access restrictions the affected users will no - longer be able to access that resource. - operationId: deleteAssignment + source: cntb get datacenters + /v1/object-storages/{objectStorageId}: + get: + description: Get data for a specific object storage on your account. + operationId: retrieveObjectStorage parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -3043,54 +2907,39 @@ paths: schema: type: string style: simple - - description: The identifier of the tag. - example: "12345" - explode: false - in: path - name: tagId - required: true - schema: - format: int64 - type: integer - style: simple - - description: The identifier of the resource type. Resource type is one of - `instance|image|object-storage`. - example: instance - explode: false - in: path - name: resourceType - required: true - schema: - type: string - style: simple - - description: The identifier of the resource id - example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + - description: The identifier of the object storage. + example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 explode: false in: path - name: resourceId + name: objectStorageId required: true schema: type: string style: simple responses: - "204": - description: Response body has no content + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/FindObjectStorageResponse' + description: The response will be a JSON object and contains standard object + storage attributes. security: - bearer: [] - summary: Delete existing tag assignment + summary: Get specific object storage by its id tags: - - Tag Assignments + - Object Storages x-codeSamples: - lang: cURL - source: 'curl -X DELETE -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345/assignments/instance/d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc"' + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc"' - lang: cntb CLI - source: cntb delete tagAssignment 12345 instance d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - get: - description: Get attributes for a specific tag assignment in your account. For - this the resource type and resource id is required. - operationId: retrieveAssignment + source: cntb get objectStorage ea639fc6-9aae-4d71-af8b-046dda87a9cc + patch: + description: Modifies the display name of object storage. Display name must + be unique. + operationId: updateObjectStorage parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -3112,60 +2961,49 @@ paths: schema: type: string style: simple - - description: The identifier of the tag. - example: "12345" - explode: false - in: path - name: tagId - required: true - schema: - format: int64 - type: integer - style: simple - - description: The identifier of the resource type. Resource type is one of - `instance|image|object-storage`. - example: instance + - description: The identifier of the object storage. + example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 explode: false in: path - name: resourceType + name: objectStorageId required: true schema: type: string style: simple - - description: The identifier of the resource id - example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - explode: false - in: path - name: resourceId + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchObjectStorageRequest' required: true - schema: - type: string - style: simple responses: "200": content: application/json: schema: - $ref: '#/components/schemas/FindAssignmentResponse' - description: The response will be a JSON object and contains standard tag - assignment attributes. + $ref: '#/components/schemas/CancelObjectStorageResponse' + description: The response will be a JSON object and contains the object + storage with updated display name. security: - bearer: [] - summary: Get specific assignment for the tag + summary: Modifies the display name of object storage tags: - - Tag Assignments + - Object Storages x-codeSamples: - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345/assignments/instance/d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc"' + source: 'curl -X PATCH "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc" + -H "accept: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: + 123213" -H "Content-Type: application/json" -d ''{ "displayName": "Object + storage EU 2"}''' - lang: cntb CLI - source: cntb get tagAssignment 12345 instance d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + source: cntb update objectStorage --displayName "Object storage EU 1" + /v1/object-storages/{objectStorageId}/resize: post: - description: Create a new tag assignment. This marks the specified resource - with the specified tag for organizing purposes or to restrict access to that - resource. - operationId: createAssignment + description: Upgrade object storage size. You can also adjust the autoscaling + settings for your object storage. Autoscaling allows you to automatically + purchase storage capacity on a monthly basis up to the specified limit. + operationId: upgradeObjectStorage parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -3187,60 +3025,50 @@ paths: schema: type: string style: simple - - description: The identifier of the tag. - example: "12345" - explode: false - in: path - name: tagId - required: true - schema: - format: int64 - type: integer - style: simple - - description: The identifier of the resource type. Resource type is one of - `instance|image|object-storage`. - example: instance + - description: The identifier of the object storage. + example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 explode: false in: path - name: resourceType + name: objectStorageId required: true schema: type: string style: simple - - description: The identifier of the resource id - example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - explode: false - in: path - name: resourceId + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpgradeObjectStorageRequest' required: true - schema: - type: string - style: simple responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/CreateAssignmentResponse' - description: The response will be a JSON object and contains standard tag - assignment attributes. + $ref: '#/components/schemas/UpgradeObjectStorageResponse' + description: The response will be a JSON object and contains standard object + storage attributes. security: - bearer: [] - summary: Create a new assignment for the tag + summary: Upgrade object storage size resp. update autoscaling settings. tags: - - Tag Assignments + - Object Storages x-codeSamples: - lang: cURL - source: 'curl -X POST "https://api.contabo.com/v1/tags/12345/assignments/instance/d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc" - -H "accept: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: - 123213"' + source: 'curl -X POST -H "accept: application/json" -H "Content-Type: application/json" + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" + -H "x-trace-id: 123213" -d ''{ "autoScaling": { "state": "enabled", "sizeLimitTB": + 6 }, "totalPurchasedSpaceTB": 8 }'' "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc/resize"' - lang: cntb CLI - source: cntb create tagAssignment 12345 instance d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - /v1/tags/audits: + source: cntb resize objectStorage ea639fc6-9aae-4d71-af8b-046dda87a9cc --totalPurchasedSpaceTB + 8 --scalingLimitTB 6 --scalingState="enabled" + /v1/object-storages/{objectStorageId}/stats: get: - description: List and filters the history about your assignments. - operationId: retrieveTagAuditsList + description: List usage statistics about the specified object storage such as + the number of objects uploaded / created, used object storage space. Please + note that the usage statistics are updated regularly and are not live usage + statistics. + operationId: retrieveObjectStoragesStats parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -3262,110 +3090,144 @@ paths: schema: type: string style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false + - description: The identifier of the object storage. + example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 + explode: false + in: path + name: objectStorageId + required: true schema: - format: int64 - type: integer - style: form - - description: Number of elements per page. - example: 10 - explode: true - in: query - name: size - required: false - schema: - format: int64 - type: integer - style: form - - description: Specify fields and ordering (ASC for ascending, DESC for descending) - in following format `field:ASC|DESC`. - example: name:asc - explode: true - in: query - name: orderBy - required: false - schema: - items: - type: string - type: array - style: form - - description: The identifier of the tag. - example: "12345" - explode: true - in: query - name: tagId - required: false + type: string + style: simple + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ObjectStoragesStatsResponse' + description: The response will be a JSON object and contains the object + storages count the current object storages and give the current quota + maximum. + security: + - bearer: [] + summary: List usage statistics about the specified object storage + tags: + - Object Storages + x-codeSamples: + - lang: cURL + source: 'curl -X GET ''https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc/stats'' + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' + -H ''x-trace-id: 123213''' + - lang: cntb CLI + source: cntb stats objectStorage 1f771979-1c0f-44ab-ab5b-2c3752731b45 + /v1/object-storages/{objectStorageId}/cancel: + patch: + description: Cancels the specified object storage at the next possible date. + Please be aware of your contract periods. + operationId: CancelObjectStorage + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true schema: - format: int64 - type: integer - style: form - - description: The requestId of the API call which led to the change. - example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 - explode: true - in: query - name: requestId + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id required: false schema: type: string - style: form - - description: UserId of the user which led to the change. - example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 - explode: true - in: query - name: changedBy - required: false + style: simple + - description: The identifier of the object storage. + example: 4a6f95be-2ac0-4e3c-8eed-0dc67afed640 + explode: false + in: path + name: objectStorageId + required: true schema: type: string - style: form - - description: Start of search time range. - example: 2021-01-01 - explode: true - in: query - name: startDate - required: false + style: simple + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/CancelObjectStorageResponse' + description: The response will be a JSON object and contains the objectstorageId + and cancel date. + security: + - bearer: [] + summary: Cancels the specified object storage at the next possible date + tags: + - Object Storages + x-codeSamples: + - lang: cURL + source: 'curl -X PATCH -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages/ea639fc6-9aae-4d71-af8b-046dda87a9cc/cancel"' + - lang: cntb CLI + source: cntb cancel objectStorage 1f771979-1c0f-44ab-ab5b-2c3752731b45 + /v1/create-ticket: + post: + description: Create a new support ticket. + operationId: createTicket + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true schema: - format: date + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - style: form - - description: End of search time range. - example: 2021-01-01 - explode: true - in: query - name: endDate + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id required: false schema: - format: date type: string - style: form + style: simple + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateTicketRequest' + required: true responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/ListTagAuditsResponse' - description: The response will be a JSON object and contains a paginated - list of tags audits. + $ref: '#/components/schemas/CreateTicketResponse' + description: The response will be a JSON object and contains standard support + ticket attributes. security: - bearer: [] - summary: List history about your assignments (audit) + summary: Create a new support ticket tags: - - Tags Audits + - Internal x-codeSamples: - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/audits"' - - lang: cntb CLI - source: cntb history tags - /v1/tags/assignments/audits: + source: 'curl -X POST ''https://api.contabo.com/v1/create-ticket'' -H "Content-Type: + application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: + 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: 123213'' -d ''{"subject": + "Subject", "note": "Note"}''' + /v1/object-storages/audits: get: - description: List and filters the history about your assignments. - operationId: retrieveAssignmentsAuditsList + description: List and filters the history about your object storages. + operationId: retrieveObjectStorageAuditsList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -3419,21 +3281,11 @@ paths: type: string type: array style: form - - description: The identifier of the tag. - example: "12345" - explode: true - in: query - name: tagId - required: false - schema: - format: int64 - type: integer - style: form - - description: The identifier of the resource. - example: a1b2c3 + - description: The identifier of the object storage. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 explode: true in: query - name: resourceId + name: objectStorageId required: false schema: type: string @@ -3447,7 +3299,7 @@ paths: schema: type: string style: form - - description: UserId of the user which led to the change. + - description: changedBy of the user which led to the change. example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 explode: true in: query @@ -3481,21 +3333,21 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListAssignmentAuditsResponse' + $ref: '#/components/schemas/ListObjectStorageAuditResponse' description: The response will be a JSON object and contains a paginated - list of assignments audits. + list of object storage audits. security: - bearer: [] - summary: List history about your assignments (audit) + summary: List history about your object storages (audit) tags: - - Tag Assignments Audits + - Object Storages Audits x-codeSamples: - lang: cURL source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - "https://api.contabo.com/v1/tags/assignments/audits"' + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/object-storages/audits"' - lang: cntb CLI - source: cntb history tagAssignment + source: cntb history objectStorages /v1/private-networks: get: description: List and filter all Private Networks in your account @@ -4080,10 +3932,10 @@ paths: -H "x-trace-id: 123213" "https://api.contabo.com/v1/private-networks/audits"' - lang: cntb CLI source: cntb history privateNetworks - /v1/tickets: - post: - description: Create a new support ticket - operationId: createSupportTicket + /v1/secrets: + get: + description: List and filter all secrets in your account. + operationId: retrieveSecretList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -4105,92 +3957,12 @@ paths: schema: type: string style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TicketCreateRequest' - required: true - responses: - "201": - content: - application/json: - schema: - $ref: '#/components/schemas/TicketCreateResponse' - description: The response will be a JSON object and contains ticket attributes - security: - - bearer: [] - summary: Create a new support ticket - tags: - - Tickets - /v1/tickets/metadata: - get: - description: Retrieve ticket metadata - operationId: retrieveTicketMetadata - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id - required: false - schema: - type: string - style: simple - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/ListTicketMetadataResponse' - description: The response will be a JSON object and contains ticket metadata - security: - - bearer: [] - summary: Retrieve ticket metadata - tags: - - Tickets - /v1/secrets: - get: - description: List and filter all secrets in your account. - operationId: retrieveSecretList - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id - required: false - schema: - type: string - style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page + required: false schema: format: int64 type: integer @@ -4601,13 +4373,10 @@ paths: -H "x-trace-id: 123213" "https://api.contabo.com/v1/secrets/audits"' - lang: cntb CLI source: cntb history secrets - /v1/compute/instances/{instanceId}/actions/start: + /v1/tickets: post: - description: Starting a compute instance / resource is like powering on a real - server. If the compute instance / resource is already started nothing will - happen. You may check the current status anytime when getting information - about a compute instance / resource. - operationId: start + description: Create a new support ticket + operationId: createSupportTicket parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -4629,39 +4398,28 @@ paths: schema: type: string style: simple - - description: The identifier of the compute instance / resource to be started - in rescue mode. - example: 12345 - explode: false - in: path - name: instanceId + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TicketCreateRequest' required: true - schema: - format: int64 - type: integer - style: simple responses: "201": content: application/json: schema: - $ref: '#/components/schemas/InstanceStartActionResponse' - description: Information of started instance + $ref: '#/components/schemas/TicketCreateResponse' + description: The response will be a JSON object and contains ticket attributes security: - bearer: [] - summary: Start a compute instance / resource identified by its id + summary: Create a new support ticket tags: - - Instance Actions - x-codeSamples: - - lang: cURL - source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/start"' - - lang: cntb CLI - source: cntb start instance 1234 - /v1/compute/instances/{instanceId}/actions/restart: - post: - description: List of your custom images history, with the ability to apply filters. - operationId: restart + - Tickets + /v1/tickets/metadata: + get: + description: Retrieve ticket metadata + operationId: retrieveTicketMetadata parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -4683,44 +4441,22 @@ paths: schema: type: string style: simple - - description: The identifier of the compute instance / resource to be started - in rescue mode. - example: 12345 - explode: false - in: path - name: instanceId - required: true - schema: - format: int64 - type: integer - style: simple responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/InstanceRestartActionResponse' - description: Information of restarted instance + $ref: '#/components/schemas/ListTicketMetadataResponse' + description: The response will be a JSON object and contains ticket metadata security: - bearer: [] - summary: Retrieve a list of your custom images history. + summary: Retrieve ticket metadata tags: - - Instance Actions - x-codeSamples: - - lang: cURL - source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/restart"' - - lang: cntb CLI - source: cntb restart instance 1234 - /v1/compute/instances/{instanceId}/actions/stop: - post: - description: Stopping a compute instance / resource is like powering off a real - server. So please be aware that data may be lost. Alternatively you may log - in and shut your compute instance / resource gracefully via the operating - system. If the compute instance / resource is already stopped nothing will - happen. You may check the current status anytime when getting information - about a compute instance / resource. - operationId: stop + - Tickets + /v1/tags: + get: + description: List and filter all tags in your account + operationId: retrieveTagList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -4742,41 +4478,73 @@ paths: schema: type: string style: simple - - description: The identifier of the compute instance / resource to be started - in rescue mode. - example: 12345 - explode: false - in: path - name: instanceId - required: true + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page + required: false schema: format: int64 type: integer - style: simple + style: form + - description: Number of elements per page. + example: 10 + explode: true + in: query + name: size + required: false + schema: + format: int64 + type: integer + style: form + - description: Specify fields and ordering (ASC for ascending, DESC for descending) + in following format `field:ASC|DESC`. + example: name:asc + explode: true + in: query + name: orderBy + required: false + schema: + items: + type: string + type: array + style: form + - description: Filter as substring match for tag names. Tags may contain letters, + numbers, colons, dashes, and underscores. There is a limit of 255 characters + per tag. + example: web + explode: true + in: query + name: name + required: false + schema: + type: string + style: form responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/InstanceStopActionResponse' - description: Information of stoped instance + $ref: '#/components/schemas/ListTagResponse' + description: The response will be a JSON object and contains a paginated + list of tags. security: - bearer: [] - summary: Stop compute instance / resource by its id + summary: List tags tags: - - Instance Actions + - Tags x-codeSamples: - lang: cURL - source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/stop"' + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags"' - lang: cntb CLI - source: cntb stop instance 1234 - /v1/compute/instances/{instanceId}/actions/shutdown: + source: cntb get tags post: - description: Shutdown an compute instance / resource. This is similar to pressing - the power button on a physical machine. This will send an ACPI event for the - guest OS, which should then proceed to a clean shutdown. - operationId: shutdown + description: Create a new tag in your account with attribute name and optional + attribute color. + operationId: createTag parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -4798,45 +4566,38 @@ paths: schema: type: string style: simple - - description: The identifier of the compute instance / resource to be started - in rescue mode. - example: 12345 - explode: false - in: path - name: instanceId + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateTagRequest' required: true - schema: - format: int64 - type: integer - style: simple responses: "201": content: application/json: schema: - $ref: '#/components/schemas/InstanceShutdownActionResponse' - description: Information of a shutdown instance + $ref: '#/components/schemas/CreateTagResponse' + description: The response will be a JSON object and contains standard tag + attributes. security: - bearer: [] - summary: Shutdown compute instance / resource by its id + summary: Create a new tag tags: - - Instance Actions + - Tags x-codeSamples: - lang: cURL - source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/shutdown"' + source: 'curl -X POST "https://api.contabo.com/v1/tags" -H "accept: application/json" + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: + 123213" -H "Content-Type: application/json" -d ''{"name":"Web-Server","color":"#0A78C3"}''' - lang: cntb CLI - source: cntb shutdown instance 1234 - /v1/compute/instances/{instanceId}/actions/rescue: - post: - description: You can reboot your instance in rescue mode to resolve system issues. - Rescue system is Linux based and its booted instead of your regular operating - system. The disk containing your operating sytstem, software and your data - is already mounted for you to access and repair/modify files. After a reboot - your compute instance will boot your operating system. Please note that this - is for advanced users. - operationId: rescue - parameters: + source: cntb create tag --name "Web-Server" --color "#0A78C3" + /v1/tags/{tagId}: + delete: + description: Your tag can be deleted if it is not assigned to any resource on + your account. Check tag assigments before deleting tag. + operationId: deleteTag + parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) to generate them manually.' @@ -4857,71 +4618,89 @@ paths: schema: type: string style: simple - - description: The identifier of the compute instance / resource to be started - in rescue mode. + - description: The identifier of the tag example: 12345 explode: false in: path - name: instanceId + name: tagId required: true schema: format: int64 type: integer style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/InstancesActionsRescueRequest' + responses: + "204": + description: Response body has no content + security: + - bearer: [] + summary: Delete existing tag by id + tags: + - Tags + x-codeSamples: + - lang: cURL + source: 'curl -X DELETE -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345"' + - lang: cntb CLI + source: cntb delete tag 12345 + get: + description: Get attributes values to a specific tag on your account. + operationId: retrieveTag + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: + type: string + style: simple + - description: The identifier of the tag + example: 12345 + explode: false + in: path + name: tagId required: true + schema: + format: int64 + type: integer + style: simple responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/InstanceRescueActionResponse' - description: Information of rescued instance + $ref: '#/components/schemas/FindTagResponse' + description: The response will be a JSON object and contains standard tag + attributes. security: - bearer: [] - summary: Rescue a compute instance / resource identified by its id + summary: Get specific tag by id tags: - - Instance Actions + - Tags x-codeSamples: - lang: cURL - source: "curl -X POST \"https://api.contabo.com/v1/compute/instances/1234/actions/rescue\"\ - \ -H \"Authorization: Bearer ${ACCESS_TOKEN}\" -H \"x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31\"\ - \ -H \"x-trace-id: 123213\" -d '{\"sshKeys\": [1,2], \"rootPassword\": 12,\ - \ \"userData\": \"#cloud-config\n user: root\n ssh_pwauth: true\n disable_root:\ - \ false\n ssh_authorized_keys:\n - \n chpasswd:\n list:\n - root:\ - \ \n expire: False\n\"}'" + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345"' - lang: cntb CLI - source: |- - cntb rescue instance 1234 --sshKeys "1,2" --rootPassword 12 --userData '#cloud-config - - - - - - - - - - - - - - - user: root - ssh_pwauth: true - disable_root: false - ssh_authorized_keys: - - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL6Bja3wXjkpxkGrNkBqcb/WeRlWO33XWnKHS/Uf9lmH testKey' - /v1/compute/instances/{instanceId}/actions/resetPassword: - post: - description: Reset password for a compute instance / resource referenced by - an id. This will reset the current password to the password that you provided - in the body of this request. - operationId: resetPasswordAction + source: cntb get tag 12345 + patch: + description: Update attributes to your tag. Attributes are optional. If not + set, the attributes will retain their original values. + operationId: updateTag parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -4943,12 +4722,11 @@ paths: schema: type: string style: simple - - description: The identifier of the compute instance / resource to be started - in rescue mode. + - description: The identifier of the tag example: 12345 explode: false in: path - name: instanceId + name: tagId required: true schema: format: int64 @@ -4958,36 +4736,32 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/InstancesResetPasswordActionsRequest' + $ref: '#/components/schemas/UpdateTagRequest' required: true responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/InstanceResetPasswordActionResponse' - description: Information of an instance password reset + $ref: '#/components/schemas/UpdateTagResponse' + description: The response will be a JSON object and contains standard tag + attributes. security: - bearer: [] - summary: Reset password for a compute instance / resource referenced by an id + summary: Update specific tag by id tags: - - Instance Actions + - Tags x-codeSamples: - lang: cURL - source: 'curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/1234/actions/resetPassword" - -d ''{"sshKeys": [1,2], "rootPassword": 12, "userData": "''#cloud-config\nuser: - root\nssh_pwauth: true\ndisable_root: false\nssh_authorized_keys:\n - \nchpasswd:\n list:\n - - root: \n expire: False\n''"}''' + source: 'curl -X PATCH -H "accept: application/json" -H "Content-Type: application/json" + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" -d ''{"name": "Updated-Web-Server"}'' "https://api.contabo.com/v1/tags/12345"' - lang: cntb CLI - source: "cntb resetPassword instance 1234 --sshKeys \"1,2\" --rootPassword\ - \ 12 --userData \"#cloud-config\n user: root\n ssh_pwauth: true\n disable_root:\ - \ false\n ssh_authorized_keys:\n - \n chpasswd:\n list:\n - root:\ - \ \n expire: False\n\"" - /v1/compute/instances: + source: cntb update tag 12345 --name "Updated-Web-Server" + /v1/tags/{tagId}/assignments: get: - description: List and filter all instances in your account - operationId: retrieveInstancesList + description: List and filter all existing assignments for a tag in your account + operationId: retrieveAssignmentList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5009,6 +4783,16 @@ paths: schema: type: string style: simple + - description: The identifier of the tag. + example: "12345" + explode: false + in: path + name: tagId + required: true + schema: + format: int64 + type: integer + style: simple - description: Number of page to be fetched. example: 1 explode: true @@ -5041,152 +4825,111 @@ paths: type: string type: array style: form - - description: The name of the instance - example: vmd12345 - explode: true - in: query - name: name - required: false - schema: - type: string - style: form - - description: The display name of the instance - example: myTestInstance + - description: Filter as substring match for assignment resource type. Resource + type is one of `instance|image|object-storage`. + example: instance explode: true in: query - name: displayName + name: resourceType required: false schema: type: string style: form - - description: The data center of the instance - example: European Union (Germany) 1 - explode: true - in: query - name: dataCenter - required: false + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListAssignmentResponse' + description: The response will be a JSON object and contains a paginated + list of tag assignments. + security: + - bearer: [] + summary: List tag assignments + tags: + - Tag Assignments + x-codeSamples: + - lang: cURL + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345/assignments"' + - lang: cntb CLI + source: cntb get tagAssignments 12345 + /v1/tags/{tagId}/assignments/{resourceType}/{resourceId}: + delete: + description: Tag assignment will be removed from the specified resource. If + this tag is being used for access restrictions the affected users will no + longer be able to access that resource. + operationId: deleteAssignment + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - style: form - - description: The Region of the instance - example: EU - explode: true - in: query - name: region + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id required: false schema: type: string - style: form - - deprecated: true - description: The identifier of the instance (deprecated) - example: 100 - explode: true - in: query - name: instanceId - required: false + style: simple + - description: The identifier of the tag. + example: "12345" + explode: false + in: path + name: tagId + required: true schema: format: int64 type: integer - style: form - - description: Comma separated instances identifiers - example: 100, 101, 102 - explode: true - in: query - name: instanceIds - required: false - schema: - type: string - style: form - - description: The status of the instance - example: provisioning,installing - explode: true - in: query - name: status - required: false - schema: - enum: - - provisioning - - uninstalled - - running - - stopped - - error - - installing - - unknown - - manual_provisioning - - product_not_available - - verification_required - - rescue - - pending_payment - - other - type: string - style: form - - description: Identifiers of Addons the instances have - example: 1044,827 - explode: true - in: query - name: addOnIds - required: false + style: simple + - description: The identifier of the resource type. Resource type is one of + `instance|image|object-storage`. + example: instance + explode: false + in: path + name: resourceType + required: true schema: type: string - style: form - - description: Comma separated instance's category depending on Product Id - example: ssd, hdd, nvme - explode: true - in: query - name: productTypes - required: false + style: simple + - description: The identifier of the resource id + example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + explode: false + in: path + name: resourceId + required: true schema: type: string - style: form - - description: Filter instances that have an ip config - example: true - explode: true - in: query - name: ipConfig - required: false - schema: - type: boolean - style: form + style: simple responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/ListInstancesResponse' - description: The response will be a JSON object and contains a paginated - list of instances. + "204": + description: Response body has no content security: - bearer: [] - summary: List instances + summary: Delete existing tag assignment tags: - - Instances + - Tag Assignments x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances'' -H ''Content-Type: - application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: - 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: 123213''' + source: 'curl -X DELETE -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345/assignments/instance/d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc"' - lang: cntb CLI - source: cntb get instances - post: - description: Create a new instance for your account with the provided parameters.
ProductIdProductDisk - Size
V45VPS 1 SSD400 GB SSD
V47VPS - 1 Storage800 GB SSD
V46VPS 1 - NVMe100 GB NVMe
V48VPS 2 SSD400 - GB SSD
V50VPS 2 Storage800 GB - SSD
V49VPS 2 NVMe200 GB NVMe
V51VPS - 3 SSD1200 GB SSD
V53VPS 3 Storage2400 - GB SSD
V52VPS 3 NVMe300 GB NVMe
V54VPS - 4 SSD1600 GB SSD
V56VPS 4 Storage3200 - GB SSD
V55VPS 4 NVMe400 GB NVMe
V57VPS - 5 SSD2000 GB SSD
V59VPS 5 Storage4000 - GB SSD
V58VPS 5 NVMe500 GB NVMe
V60VPS - 6 SSD2400 GB SSD
V62VPS 6 Storage4800 - GB SSD
V61VPS 6 NVMe600 GB NVMe
V8VDS - S180 GB NVMe
V9VDS M240 - GB NVMe
V10VDS L360 GB NVMe
V11VDS - XL480 GB NVMe
V16VDS XXL720 - GB NVMe
- operationId: createInstance + source: cntb delete tagAssignment 12345 instance d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + get: + description: Get attributes for a specific tag assignment in your account. For + this the resource type and resource id is required. + operationId: retrieveAssignment parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5208,39 +4951,60 @@ paths: schema: type: string style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateInstanceRequest' + - description: The identifier of the tag. + example: "12345" + explode: false + in: path + name: tagId + required: true + schema: + format: int64 + type: integer + style: simple + - description: The identifier of the resource type. Resource type is one of + `instance|image|object-storage`. + example: instance + explode: false + in: path + name: resourceType + required: true + schema: + type: string + style: simple + - description: The identifier of the resource id + example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + explode: false + in: path + name: resourceId required: true + schema: + type: string + style: simple responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/CreateInstanceResponse' - description: The response will be a JSON object and contains standard instance - attributes. + $ref: '#/components/schemas/FindAssignmentResponse' + description: The response will be a JSON object and contains standard tag + assignment attributes. security: - bearer: [] - summary: Create a new instance + summary: Get specific assignment for the tag tags: - - Instances + - Tag Assignments x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances'' -H - "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: - 123213'' -d ''{"region": "EU", "productId": "V1", "imageId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", - "period": 1}''' + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/12345/assignments/instance/d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc"' - lang: cntb CLI - source: create instance --period 1 --imageId "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" - --productId "V1" -r "EU" - /v1/compute/instances/{instanceId}: - get: - description: Get attributes values to a specific instance on your account. - operationId: retrieveInstance + source: cntb get tagAssignment 12345 instance d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + post: + description: Create a new tag assignment. This marks the specified resource + with the specified tag for organizing purposes or to restrict access to that + resource. + operationId: createAssignment parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5262,40 +5026,60 @@ paths: schema: type: string style: simple - - description: The identifier of the instance - example: 12345 + - description: The identifier of the tag. + example: "12345" explode: false in: path - name: instanceId + name: tagId required: true schema: format: int64 type: integer style: simple + - description: The identifier of the resource type. Resource type is one of + `instance|image|object-storage`. + example: instance + explode: false + in: path + name: resourceType + required: true + schema: + type: string + style: simple + - description: The identifier of the resource id + example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + explode: false + in: path + name: resourceId + required: true + schema: + type: string + style: simple responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/FindInstanceResponse' - description: The response will be a JSON object and contains standard instance - attributes. + $ref: '#/components/schemas/CreateAssignmentResponse' + description: The response will be a JSON object and contains standard tag + assignment attributes. security: - bearer: [] - summary: Get specific instance by id + summary: Create a new assignment for the tag tags: - - Instances + - Tag Assignments x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances/12345'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H ''x-trace-id: - 123213''' + source: 'curl -X POST "https://api.contabo.com/v1/tags/12345/assignments/instance/d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc" + -H "accept: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" -H "x-trace-id: + 123213"' - lang: cntb CLI - source: cntb get instance 12345 - patch: - description: Update specific instance by instanceId. - operationId: patchInstance + source: cntb create tagAssignment 12345 instance d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + /v1/tags/audits: + get: + description: List and filters the history about your assignments. + operationId: retrieveTagAuditsList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5317,231 +5101,110 @@ paths: schema: type: string style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page + required: false schema: format: int64 type: integer - style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchInstanceRequest' - required: true - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/PatchInstanceResponse' - description: The response will be a JSON object and contains instanceId - and createdDate. - security: - - bearer: [] - summary: Update specific instance - tags: - - Instances - x-codeSamples: - - lang: cURL - source: 'curl -X PATCH ''https://api.contabo.com/v1/compute/instances/12345'' - -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: - 123213" -d ''{"displayName": "VPS"}''' - - lang: cntb CLI - source: cntb update instance 12345 --displayName "VPS" - put: - description: You can reinstall a specific instance with a new image and optionally - add ssh keys, a root password or cloud-init. - operationId: reinstallInstance - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true + style: form + - description: Number of elements per page. + example: 10 + explode: true + in: query + name: size + required: false schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + format: int64 + type: integer + style: form + - description: Specify fields and ordering (ASC for ascending, DESC for descending) + in following format `field:ASC|DESC`. + example: name:asc + explode: true + in: query + name: orderBy required: false schema: - type: string - style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true + items: + type: string + type: array + style: form + - description: The identifier of the tag. + example: "12345" + explode: true + in: query + name: tagId + required: false schema: format: int64 type: integer - style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ReinstallInstanceRequest' - required: true - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/ReinstallInstanceResponse' - description: The response will be a JSON object and contains instanceId - and createdDate. - security: - - bearer: [] - summary: Reinstall specific instance - tags: - - Instances - x-codeSamples: - - lang: cURL - source: 'curl -X PUT ''https://api.contabo.com/v1/compute/instances/12345'' - -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: - 123213" -d ''{"imageId": "a2c26e8f-84a5-4f3e-9c0e-b06511928cc0", "sshKeys": - [1,2], "rootPassword": 12}''' - - lang: cntb CLI - source: cntb reinstall instance 12345 --imageId "a2c26e8f-84a5-4f3e-9c0e-b06511928cc0" - --sshKeys "1,2" --rootPassword 12 - /v1/compute/instances/{instanceId}/cancel: - post: - description: Your are free to cancel a previously created instance at any time. - operationId: cancelInstance - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true + style: form + - description: The requestId of the API call which led to the change. + example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 + explode: true + in: query + name: requestId + required: false schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + style: form + - description: UserId of the user which led to the change. + example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 + explode: true + in: query + name: changedBy required: false schema: type: string - style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true - schema: - format: int64 - type: integer - style: simple - responses: - "201": - content: - application/json: - schema: - $ref: '#/components/schemas/CancelInstanceResponse' - description: The response will be a JSON object and contains standard custom - image attributes - security: - - bearer: [] - summary: Cancel specific instance by id - tags: - - Instances - x-codeSamples: - - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/cancel'' - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' - -H ''x-trace-id: 123213''' - - lang: cntb CLI - source: cntb cancel instance 12345 - /v1/compute/instances/{instanceId}/upgrade: - post: - description: In order to enhance your instance with additional features you - can purchase add-ons. Currently only firewalling and private network addon - is allowed. - operationId: upgradeInstance - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true + style: form + - description: Start of search time range. + example: 2021-01-01 + explode: true + in: query + name: startDate + required: false schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + format: date type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + style: form + - description: End of search time range. + example: 2021-01-01 + explode: true + in: query + name: endDate required: false schema: + format: date type: string - style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true - schema: - format: int64 - type: integer - style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UpgradeInstanceRequest' - required: true + style: form responses: "200": content: application/json: schema: - $ref: '#/components/schemas/PatchInstanceResponse' - description: The response will be a JSON object and contains standard instance - attributes. + $ref: '#/components/schemas/ListTagAuditsResponse' + description: The response will be a JSON object and contains a paginated + list of tags audits. security: - bearer: [] - summary: Upgrading instance capabilities + summary: List history about your assignments (audit) tags: - - Instances + - Tags Audits x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/upgrade'' - -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H "x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406" -H "x-trace-id: - 123213" -d ''{ "privateNetworking": {} }''' + source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: + Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" + -H "x-trace-id: 123213" "https://api.contabo.com/v1/tags/audits"' - lang: cntb CLI - source: cntb upgrade instance 12345 --privateNetworking=true - /v1/compute/instances/actions/audits: + source: cntb history tags + /v1/tags/assignments/audits: get: - description: List and filters the history about your actions your triggered - via the API. - operationId: retrieveInstancesActionsAuditsList + description: List and filters the history about your assignments. + operationId: retrieveAssignmentsAuditsList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5595,16 +5258,25 @@ paths: type: string type: array style: form - - description: The identifier of the instancesActions. - example: 12345 + - description: The identifier of the tag. + example: "12345" explode: true in: query - name: instanceId + name: tagId required: false schema: format: int64 type: integer style: form + - description: The identifier of the resource. + example: a1b2c3 + explode: true + in: query + name: resourceId + required: false + schema: + type: string + style: form - description: The requestId of the API call which led to the change. example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 explode: true @@ -5614,7 +5286,7 @@ paths: schema: type: string style: form - - description: changedBy of the user which led to the change. + - description: UserId of the user which led to the change. example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 explode: true in: query @@ -5624,7 +5296,7 @@ paths: type: string style: form - description: Start of search time range. - example: 2021-06-02 + example: 2021-01-01 explode: true in: query name: startDate @@ -5634,7 +5306,7 @@ paths: type: string style: form - description: End of search time range. - example: 2021-06-02 + example: 2021-01-01 explode: true in: query name: endDate @@ -5648,25 +5320,25 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListInstancesActionsAuditResponse' + $ref: '#/components/schemas/ListAssignmentAuditsResponse' description: The response will be a JSON object and contains a paginated - list of action audits triggered via the API. + list of assignments audits. security: - bearer: [] - summary: List history about your actions (audit) triggered via the API + summary: List history about your assignments (audit) tags: - - Instance Actions Audits + - Tag Assignments Audits x-codeSamples: - lang: cURL source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/actions/audits"' + "https://api.contabo.com/v1/tags/assignments/audits"' - lang: cntb CLI - source: cntb history instancesActions - /v1/compute/instances/audits: + source: cntb history tagAssignment + /v1/users: get: - description: List and filters the history about your custom images. - operationId: retrieveInstancesAuditsList + description: List and filter all your users. + operationId: retrieveUserList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5720,147 +5392,29 @@ paths: type: string type: array style: form - - description: The identifier of the instances. - example: 12345 - explode: true - in: query - name: instanceId - required: false - schema: - format: int64 - type: integer - style: form - - description: The requestId of the API call which led to the change. - example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 - explode: true - in: query - name: requestId - required: false - schema: - type: string - style: form - - description: changedBy of the user which led to the change. - example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 - explode: true - in: query - name: changedBy - required: false - schema: - type: string - style: form - - description: Start of search time range. - example: 2021-06-02 - explode: true - in: query - name: startDate - required: false - schema: - format: date - type: string - style: form - - description: End of search time range. - example: 2021-06-02 + - description: Filter as substring match for user emails. + example: john.doe@example.com explode: true in: query - name: endDate - required: false - schema: - format: date - type: string - style: form - responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/ListInstancesAuditResponse' - description: The response will be a JSON object and contains a paginated - list of instances audits triggered via the API. - security: - - bearer: [] - summary: List history about your custom images (audit) - tags: - - Instances Audits - x-codeSamples: - - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/instances/audits"' - - lang: cntb CLI - source: cntb history instances - /v1/compute/images: - get: - description: List and filter all available standard images provided by [Contabo](https://contabo.com) - and your uploaded custom images. - operationId: retrieveImageList - parameters: - - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) - to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) - to generate them manually.' - explode: false - in: header - name: x-request-id - required: true - schema: - example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 - pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ - type: string - style: simple - - description: Identifier to trace group of requests. - explode: false - in: header - name: x-trace-id + name: email required: false schema: type: string - style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false - schema: - format: int64 - type: integer - style: form - - description: Number of elements per page. - example: 10 - explode: true - in: query - name: size - required: false - schema: - format: int64 - type: integer - style: form - - description: Specify fields and ordering (ASC for ascending, DESC for descending) - in following format `field:ASC|DESC`. - example: name:asc - explode: true - in: query - name: orderBy - required: false - schema: - items: - type: string - type: array style: form - - description: The name of the image - example: Ubuntu + - description: Filter if user is enabled or not. + example: "true" explode: true in: query - name: name + name: enabled required: false schema: - type: string + type: boolean style: form - - description: Flag indicating that image is either a standard (true) or a custom - image (false) - example: true + - description: Filter if user is owner or not. + example: "true" explode: true in: query - name: standardImage + name: owner required: false schema: type: boolean @@ -5870,29 +5424,28 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListImageResponse' + $ref: '#/components/schemas/ListUserResponse' description: The response will be a JSON object and contains a paginated - list of images. + list of users. security: - bearer: [] - summary: List available standard and custom images + summary: List users tags: - - Images + - Users x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/compute/images'' -H ''Content-Type: + source: 'curl -X GET ''https://api.contabo.com/v1/users'' -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb get images + source: cntb get users post: - description: In order to provide a custom image please specify an URL from where - the image can be directly downloaded. A custom image must be in either `.iso` - or `.qcow2` format. Other formats will be rejected. Please note that downloading - can take a while depending on network speed resp. bandwidth and size of image. - You can check the status by retrieving information about the image via a GET - request. Download will be rejected if you have exceeded your limits. - operationId: createCustomImage + description: Create a new user with required attributes name, email, enabled, + totp (=Two-factor authentication 2FA), admin (=access to all endpoints and + resources), accessAllResources and roles. You can't specify any password / + secrets for the user. For security reasons the user will have to specify secrets + on his own. + operationId: createUser parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5918,44 +5471,37 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CreateCustomImageRequest' + $ref: '#/components/schemas/CreateUserRequest' required: true responses: "201": content: application/json: schema: - $ref: '#/components/schemas/CreateCustomImageResponse' - description: The response will be a JSON object and contains standard custom - image attributes - "415": - content: - application/json: - schema: - $ref: '#/components/schemas/CreateCustomImageFailResponse' - description: The response will be an error in case the provided image URL - is not in .qcow2 or .iso format + $ref: '#/components/schemas/CreateUserResponse' + description: The response will be a JSON object and contains standard user + attributes. security: - bearer: [] - summary: Provide a custom image + summary: Create a new user tags: - - Images + - Users x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/compute/images'' -H ''Content-Type: + source: 'curl -X POST ''https://api.contabo.com/v1/users'' -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: - 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{"name": - "Ubuntu Custom Image", "description": "Ubuntu Server 20.04.2 LTS", "url": - "https://example.com/image.qcow2", "osType": "Linux", "version": "20.04.2"}''' + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{ + "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", + "enabled": true, "totp": false, "locale": "en", "roles": [2]}''' - lang: cntb CLI - source: cntb create image --name 'Ubuntu Custom Image' --description 'Ubuntu - Server 20.04.2 LTS' --url https://example.com/image.qcow2 --osType Linux - --version 20.04.2 - /v1/compute/images/{imageId}: + source: cntb create user --firstName John --lastName Doe --email john.doe@example.com + --enabled --locale en --roles 2 + /v1/users/{userId}: delete: - description: Your are free to delete a previously uploaded custom images at - any time - operationId: deleteImage + description: By deleting a user he will not be able to access any endpoints + or resources any longer. In order to temporarily disable a user please update + its `enabled` attribute. + operationId: deleteUser parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -5977,11 +5523,11 @@ paths: schema: type: string style: simple - - description: The identifier of the image - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 explode: false in: path - name: imageId + name: userId required: true schema: type: string @@ -5991,22 +5537,20 @@ paths: description: Response body has no content security: - bearer: [] - summary: Delete an uploaded custom image by its id + summary: Delete existing user by id tags: - - Images + - Users x-codeSamples: - lang: cURL - source: 'curl -X DELETE ''https://api.contabo.com/v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'' + source: 'curl -X DELETE ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8'' -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb delete image 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + source: cntb delete user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 get: - description: Get details about a specific image. This could be either a standard - or custom image. In case of an custom image you can also check the download - status - operationId: retrieveImage + description: Get attributes for a specific user. + operationId: retrieveUser parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6028,11 +5572,11 @@ paths: schema: type: string style: simple - - description: The identifier of the image - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 explode: false in: path - name: imageId + name: userId required: true schema: type: string @@ -6042,25 +5586,27 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/FindImageResponse' - description: The response will be a JSON object and contains standard custom - image attributes - security: + $ref: '#/components/schemas/FindUserResponse' + description: The response will be a JSON object and contains standard user + attributes. + security: - bearer: [] - summary: Get details about a specific image by its id + summary: Get specific user by id tags: - - Images + - Users x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'' + source: 'curl -X GET ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8'' -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb get image 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + source: cntb get user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 patch: - description: Update name of the custom image - operationId: updateImage + description: Update attributes of a user. You may only specify the attributes + you want to change. If an attribute is not set, it will retain its original + value. + operationId: updateUser parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6082,11 +5628,11 @@ paths: schema: type: string style: simple - - description: The identifier of the image - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 explode: false in: path - name: imageId + name: userId required: true schema: type: string @@ -6095,36 +5641,34 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/UpdateCustomImageRequest' + $ref: '#/components/schemas/UpdateUserRequest' required: true responses: "200": content: application/json: schema: - $ref: '#/components/schemas/UpdateCustomImageResponse' - description: The response will be a JSON object and contains standard custom - image attributes + $ref: '#/components/schemas/UpdateUserResponse' + description: The response will be a JSON object and contains standard user + attributes. security: - bearer: [] - summary: Update custom image name by its id + summary: Update specific user by id tags: - - Images + - Users x-codeSamples: - lang: cURL - source: 'curl -X PATCH ''https://api.contabo.com/v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'' + source: 'curl -X PATCH ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8'' -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213'' -d ''{"name": "Ubuntu Custom Image"}''' + 123213'' -d ''{"enabled":true,"roles":[1,2,3]}''' - lang: cntb CLI - source: cntb update image 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d --name 'Ubuntu - Custom Image' - /v1/compute/images/stats: - get: - description: List statistics regarding the customer's custom images such as - the number of custom images uploaded, used disk space, free available disk - space and total available disk space - operationId: retrieveCustomImagesStats + source: cntb update user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 --enabled --roles + 1 + /v1/users/{userId}/reset-password: + post: + description: Send reset password email for a specific user + operationId: resetPassword parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6146,32 +5690,43 @@ paths: schema: type: string style: simple + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + explode: false + in: path + name: userId + required: true + schema: + type: string + style: simple + - description: The redirect url used for resetting password + example: https://test.contabo.de + explode: true + in: query + name: redirectUrl + required: false + schema: + type: string + style: form responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/CustomImagesStatsResponse' - description: The response will be a JSON object and contains the custom - images count, the total available disk space, the used disk space and - the free disk space. + "204": + description: Response body has no content security: - bearer: [] - summary: List statistics regarding the customer's custom images + summary: Send reset password email tags: - - Images + - Users x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/compute/images/stats'' -H - ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' + source: 'curl -X POST ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/reset-password'' + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' + -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb get images stats - /v1/compute/instances/{instanceId}/snapshots: - get: - description: List and filter all your snapshots for a specific instance - operationId: retrieveSnapshotList + source: cntb resetPassword user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + /v1/users/{userId}/resend-email-verification: + post: + description: Resend email verification for a specific user + operationId: resendEmailVerification parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6193,81 +5748,86 @@ paths: schema: type: string style: simple - - description: The identifier of the instance - example: 12345 + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 explode: false in: path - name: instanceId + name: userId required: true schema: - format: int64 - type: integer + type: string style: simple - - description: Number of page to be fetched. - example: 1 - explode: true - in: query - name: page - required: false - schema: - format: int64 - type: integer - style: form - - description: Number of elements per page. - example: 10 + - description: The redirect url used for email verification + example: https://test.contabo.de explode: true in: query - name: size + name: redirectUrl required: false schema: - format: int64 - type: integer + type: string style: form - - description: Specify fields and ordering (ASC for ascending, DESC for descending) - in following format `field:ASC|DESC`. - example: name:asc - explode: true - in: query - name: orderBy - required: false + responses: + "204": + description: Response body has no content + security: + - bearer: [] + summary: Resend email verification + tags: + - Users + x-codeSamples: + - lang: cURL + source: 'curl -X POST ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/resend-email-verification'' + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' + -H ''x-trace-id: 123213''' + - lang: cntb CLI + source: cntb resendEmailVerification user 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + /v1/users/client: + get: + description: Get idm client. + operationId: retrieveUserClient + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true schema: - items: - type: string - type: array - style: form - - description: Filter as substring match for snapshots names. - example: Snapshot.Server - explode: true - in: query - name: name + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id required: false schema: type: string - style: form + style: simple responses: "200": content: application/json: schema: - $ref: '#/components/schemas/ListSnapshotResponse' - description: The response will be a JSON object and contains a paginated - list of snapshots attributes + $ref: '#/components/schemas/FindClientResponse' + description: The response will be a JSON object and contains standard client + attributes. security: - bearer: [] - summary: List snapshots + summary: Get client tags: - - Snapshots + - Users x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances/12345/snapshots'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' - - lang: cntb CLI - source: cntb get snapshots 12345 - post: - description: Create a new snapshot for instance, with name and description attributes - operationId: createSnapshot + source: 'curl -X GET ''https://api.contabo.com/v1/users/client'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' + /v1/users/client/secret: + put: + description: Generate and get new client secret. + operationId: generateClientSecret parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6289,48 +5849,30 @@ paths: schema: type: string style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true - schema: - format: int64 - type: integer - style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateSnapshotRequest' - required: true responses: - "201": + "200": content: application/json: schema: - $ref: '#/components/schemas/CreateSnapshotResponse' - description: The response will be a JSON object and contains standard snapshot - attributes + $ref: '#/components/schemas/GenerateClientSecretResponse' + description: The response will be a JSON object and contains new client + secret. security: - bearer: [] - summary: Create a new instance snapshot + summary: Generate new client secret tags: - - Snapshots + - Users x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/snapshots'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213'' -d ''{"name":"Snapshot-Server","description":"Snapshot-Description"}''' + source: 'curl -X PUT ''https://api.contabo.com/v1/users/client/secret'' -H + "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' + -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb create snapshot 12345 --name 'Snapshot-Server' --description - 'Snapshot-Description' - /v1/compute/instances/{instanceId}/snapshots/{snapshotId}: - delete: - description: Delete existing instance snapshot by id - operationId: deleteSnapshot + source: cntb generateSecret user + /v1/users/is-password-set: + get: + description: Get info about idm user if the password is set. + operationId: retrieveUserIsPasswordSet parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6352,44 +5894,33 @@ paths: schema: type: string style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true - schema: - format: int64 - type: integer - style: simple - - description: The identifier of the snapshot - example: snap1628603855 - explode: false - in: path - name: snapshotId - required: true + - description: The user ID for checking if password is set for him + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + explode: true + in: query + name: userId + required: false schema: type: string - style: simple + style: form responses: - "204": - description: Response body has no content + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/FindUserIsPasswordSetResponse' + description: The response will be a JSON object and contains standard user + attributes. security: - bearer: [] - summary: Delete existing snapshot by id + summary: Get user is password set status tags: - - Snapshots - x-codeSamples: - - lang: cURL - source: 'curl -X DELETE ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' - - lang: cntb CLI - source: cntb delete snapshot 12345 snap1628603855 + - Internal + /v1/roles: get: - description: Get all attributes for a specific snapshot - operationId: retrieveSnapshot + description: List and filter all your roles. A role allows you to specify permission + to api endpoints and resources like compute. + operationId: retrieveRoleList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6411,51 +5942,100 @@ paths: schema: type: string style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page + required: false schema: format: int64 type: integer - style: simple - - description: The identifier of the snapshot - example: snap1628603855 - explode: false - in: path - name: snapshotId - required: true + style: form + - description: Number of elements per page. + example: 10 + explode: true + in: query + name: size + required: false + schema: + format: int64 + type: integer + style: form + - description: Specify fields and ordering (ASC for ascending, DESC for descending) + in following format `field:ASC|DESC`. + example: name:asc + explode: true + in: query + name: orderBy + required: false + schema: + items: + type: string + type: array + style: form + - description: The name of the role + example: Web + explode: true + in: query + name: name + required: false schema: type: string - style: simple + style: form + - description: The name of api + example: /v1/compute/instances + explode: true + in: query + name: apiName + required: false + schema: + type: string + style: form + - description: The name of the tag + example: Web + explode: true + in: query + name: tagName + required: false + schema: + type: string + style: form + - description: The type of the tag. Can be either `default` or `custom` + example: custom + explode: true + in: query + name: type + required: false + schema: + type: string + style: form responses: "200": content: application/json: schema: - $ref: '#/components/schemas/FindSnapshotResponse' - description: The response will be a JSON object and contains standard snapshot - attributes + $ref: '#/components/schemas/ListRoleResponse' + description: The response will be a JSON object and contains a paginated + list of roles. security: - bearer: [] - summary: Retrieve a specific snapshot by id + summary: List roles tags: - - Snapshots + - Roles x-codeSamples: - lang: cURL - source: 'curl -X GET ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213''' + source: 'curl -X GET ''https://api.contabo.com/v1/roles'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb get snapshot 12345 snap1628603855 - patch: - description: Update attributes of a snapshot. You may only specify the attributes - you want to change. If an attribute is not set, it will retain its original - value. - operationId: updateSnapshot + source: cntb get roles + post: + description: Create a new role. In order to get a list availbale api enpoints + (apiName) and their actions please refer to the GET api-permissions endpoint. + For specifying `resources` please enter tag ids. For those to take effect + please assign them to a resource in the tag management api. + operationId: createRole parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6477,58 +6057,41 @@ paths: schema: type: string style: simple - - description: The identifier of the instance - example: 12345 - explode: false - in: path - name: instanceId - required: true - schema: - format: int64 - type: integer - style: simple - - description: The identifier of the snapshot - example: snap1628603855 - explode: false - in: path - name: snapshotId - required: true - schema: - type: string - style: simple requestBody: content: application/json: schema: - $ref: '#/components/schemas/UpdateSnapshotRequest' + $ref: '#/components/schemas/CreateRoleRequest' required: true responses: - "200": + "201": content: application/json: schema: - $ref: '#/components/schemas/UpdateSnapshotResponse' - description: The response will be a JSON object and contains standard snapshot - attributes + $ref: '#/components/schemas/CreateRoleResponse' + description: The response will be a JSON object and contains standard role + attributes. security: - bearer: [] - summary: Update specific snapshot by id + summary: Create a new role tags: - - Snapshots + - Roles x-codeSamples: - lang: cURL - source: 'curl -X PATCH ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855'' - -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" - -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: - 123213'' -d ''{"name":"Snapshot"}''' + source: 'curl -X POST ''https://api.contabo.com/v1/roles'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{"name":"infrastructure","permissions":{ + "apiName": "/v1/compute/instances", "actions": [ "CREATE", "READ" ], "resources": + [1111,2222] } }''' - lang: cntb CLI - source: cntb update snapshot 12345 snap1628603855 --name 'Snapshot' - /v1/compute/instances/{instanceId}/snapshots/{snapshotId}/rollback: - post: - description: Rollback instance to a specific snapshot. The snapshot must be - the latest one in order to be able to restore it, otherwise you will receive - an error informing you that the snapshot is not the latest - operationId: rollbackSnapshot + source: 'cntb create role --name "infrastructure" --permissions ''[{"apiName" + : "/v1/compute/instances", "actions": ["CREATE", "READ"], "resources": [1111, + 2222]}]''' + /v1/roles/{roleId}: + delete: + description: You can't delete a role if it is still assigned to a user. In such + cases please remove the role from the users. + operationId: deleteRole parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6550,55 +6113,155 @@ paths: schema: type: string style: simple - - description: The identifier of the instance + - description: The identifier of the role example: 12345 explode: false in: path - name: instanceId + name: roleId required: true schema: format: int64 type: integer style: simple - - description: The identifier of the snapshot - example: snap1628603855 - explode: false - in: path - name: snapshotId - required: true - schema: - type: string - style: simple - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RollbackSnapshotRequest' - required: true responses: - "200": - content: - application/json: - schema: - $ref: '#/components/schemas/RollbackSnapshotResponse' - description: The response will be a JSON object and contains standard snapshot - attributes + "204": + description: Response body has no content security: - bearer: [] - summary: Revert the instance to a particular snapshot based on its identifier + summary: Delete existing role by id tags: - - Snapshots + - Roles x-codeSamples: - lang: cURL - source: 'curl -X POST ''https://api.contabo.com/v1/compute/instances/12345/snapshots/snap1628603855/rollback'' - -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' - -H ''x-trace-id: 123213''' + source: 'curl -X DELETE ''https://api.contabo.com/v1/roles/12345'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb rollback snapshot 12345 snap1628603855 - /v1/compute/images/audits: + source: cntb delete role 12345 get: - description: List and filters the history about your custom images. - operationId: retrieveImageAuditsList + description: Get attributes of specific role. + operationId: retrieveRole + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: + type: string + style: simple + - description: The identifier of the role + example: 12345 + explode: false + in: path + name: roleId + required: true + schema: + format: int64 + type: integer + style: simple + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/FindRoleResponse' + description: The response will be a JSON object and contains standard role + attributes. + security: + - bearer: [] + summary: Get specific role by id + tags: + - Roles + x-codeSamples: + - lang: cURL + source: 'curl -X GET ''https://api.contabo.com/v1/roles/12345'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' + - lang: cntb CLI + source: cntb get role 12345 + put: + description: Update attributes to your role. Attributes are optional. If not + set, the attributes will retain their original values. + operationId: updateRole + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: + type: string + style: simple + - description: The identifier of the role + example: 12345 + explode: false + in: path + name: roleId + required: true + schema: + format: int64 + type: integer + style: simple + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateRoleRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateRoleResponse' + description: The response will be a JSON object and contains standard role + attributes. + security: + - bearer: [] + summary: Update specific role by id + tags: + - Roles + x-codeSamples: + - lang: cURL + source: 'curl -X PATCH ''https://api.contabo.com/v1/roles/12345'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213'' -d ''{"name":"infrastructure","permissions":[ + {"apiName": "/v1/compute/instances", "actions": ["READ"] }], "accessAllResources": + true }''' + - lang: cntb CLI + source: 'cntb update role 12345 --name newName --permissions ''[{"apiName" + : "/v1/compute/instances", "actions": ["CREATE", "READ"]}]'' --accessAllResources' + /v1/roles/api-permissions: + get: + description: List all available API permissions. This list serves as a reference + for specifying roles. As endpoints differ in their possibilities not all actions + are available for each endpoint. + operationId: retrieveApiPermissionsList parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6652,51 +6315,13 @@ paths: type: string type: array style: form - - description: The identifier of the image. - example: e443eab5-647a-4bc3-b4f9-16f5a281224d - explode: true - in: query - name: imageId - required: false - schema: - type: string - style: form - - description: The requestId of the API call which led to the change. - example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 - explode: true - in: query - name: requestId - required: false - schema: - type: string - style: form - - description: UserId of the user which led to the change. - example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 - explode: true - in: query - name: changedBy - required: false - schema: - type: string - style: form - - description: Start of search time range. - example: 2021-06-02 - explode: true - in: query - name: startDate - required: false - schema: - format: date - type: string - style: form - - description: End of search time range. - example: 2021-06-02 + - description: The name of api + example: /v1/compute/instances explode: true in: query - name: endDate + name: apiName required: false schema: - format: date type: string style: form responses: @@ -6704,26 +6329,26 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ImageAuditResponse' + $ref: '#/components/schemas/ListApiPermissionResponse' description: The response will be a JSON object and contains a paginated - list of custom images audits. + list of API permissions. security: - bearer: [] - summary: List history about your custom images (audit) + summary: List of API permissions tags: - - Images Audits + - Roles x-codeSamples: - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/images/audits"' + source: 'curl -X GET ''https://api.contabo.com/v1/api-permissions'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: 123213''' - lang: cntb CLI - source: cntb history images - /v1/compute/snapshots/audits: + source: cntb get permissions + /v1/users/{userId}/object-storages/credentials: get: - description: List and filters the history about your snapshots your triggered - via the API. - operationId: retrieveSnapshotsAuditsList + description: Get list of S3 compatible object storage credentials for accessing + it via S3 compatible tools like `aws` cli. + operationId: listObjectStorageCredentials parameters: - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) @@ -6745,6 +6370,15 @@ paths: schema: type: string style: simple + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + explode: false + in: path + name: userId + required: true + schema: + type: string + style: simple - description: Number of page to be fetched. example: 1 explode: true @@ -6777,61 +6411,32 @@ paths: type: string type: array style: form - - description: The identifier of the instance - example: 12345 - explode: true - in: query - name: instanceId - required: false - schema: - format: int64 - type: integer - style: form - - description: The identifier of the snapshot - example: snap1628603855 - explode: true - in: query - name: snapshotId - required: false - schema: - type: string - style: form - - description: The requestId of the API call which led to the change - example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 - explode: true - in: query - name: requestId - required: false - schema: - type: string - style: form - - description: changedBy of the user which led to the change - example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 + - description: The identifier of the S3 object storage + example: d8417276-d2d9-43a9-a0a8-9a6fa6060246 explode: true in: query - name: changedBy + name: objectStorageId required: false schema: type: string style: form - - description: Start of search time range. - example: 2021-06-02 + - description: 'Filter for Object Storage by regions. Available regions: Asia + (Singapore), European Union (Germany), United States (Central)' + example: Asia (Singapore) explode: true in: query - name: startDate + name: regionName required: false schema: - format: date type: string style: form - - description: End of search time range. - example: 2021-06-02 + - description: Filter for Object Storage by his displayName. + example: Object Storage EU 420 explode: true in: query - name: endDate + name: displayName required: false schema: - format: date type: string style: form responses: @@ -6839,594 +6444,496 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ListSnapshotsAuditResponse' - description: The response will be a JSON object and contains a paginated - list of snapshots audits triggered via the API. - security: - - bearer: [] - summary: List history about your snapshots (audit) triggered via the API + $ref: '#/components/schemas/ListCredentialResponse' + description: The response will be an array of JSON objects that contains + S3 credentials. + security: + - bearer: [] + summary: Get list of S3 compatible object storage credentials for user. tags: - - Snapshots Audits + - Users x-codeSamples: - lang: cURL - source: 'curl -X GET -H "Content-Type: application/json" -H "Authorization: - Bearer ${ACCESS_TOKEN}" -H "x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31" - -H "x-trace-id: 123213" "https://api.contabo.com/v1/compute/snapshots/audits"' + source: 'curl -X GET ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/object-storages/credentials'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' - lang: cntb CLI - source: cntb history snapshots -components: - schemas: - PaginationMeta: - properties: - size: - description: Number of elements per page. - example: 10 - type: number - totalElements: - description: Number of overall matched elements. - example: 100 - type: number - totalPages: - description: Overall number of pages. - example: 10 - type: number - page: - description: Current number of page. - example: 1 - type: number - required: - - page - - size - - totalElements - - totalPages - type: object - ResourcePermissionsResponse: - example: - tagId: 12345 - tagName: Web - properties: - tagId: - description: Tag's id - example: 12345 - format: int64 - type: integer - tagName: - description: Tag name. The resriction is based on the resources which have - been assigned to that tag. If no resource has been assigned to the given - tag, no access will be possible. - example: Web + source: cntb get user-credentials 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + /v1/users/{userId}/object-storages/{objectStorageId}/credentials/{credentialId}: + get: + description: Get S3 compatible object storage credentials for accessing it via + S3 compatible tools like `aws` cli. + operationId: getObjectStorageCredentials + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - required: - - tagId - - tagName - type: object - PermissionResponse: - example: - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - properties: - apiName: - description: API endpoint. In order to get a list availbale api enpoints - please refer to the GET api-permissions endpoint. - example: /v1/compute/instances + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: type: string - actions: - description: Action allowed for the API endpoint. Basically `CREATE` corresponds - to POST endpoints, `READ` to GET endpoints, `UPDATE` to PATCH / PUT endpoints - and `DELETE` to DELETE endpoints. - example: - - CREATE - - READ - items: - enum: - - CREATE - - READ - - UPDATE - - DELETE - type: string - type: array - resources: - items: - $ref: '#/components/schemas/ResourcePermissionsResponse' - type: array - required: - - actions - - apiName - type: object - RoleResponse: - example: - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - properties: - roleId: - description: Role's id - example: 12345 + style: simple + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + explode: false + in: path + name: userId + required: true + schema: + type: string + style: simple + - description: The identifier of the S3 object storage + example: d8417276-d2d9-43a9-a0a8-9a6fa6060246 + explode: false + in: path + name: objectStorageId + required: true + schema: + type: string + style: simple + - description: The ID of the object storage credential + example: 12345 + explode: false + in: path + name: credentialId + required: true + schema: format: int64 type: integer - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 + style: simple + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/FindCredentialResponse' + description: The response will be a JSON object and contains S3 credentials. + security: + - bearer: [] + summary: Get S3 compatible object storage credentials. + tags: + - Users + x-codeSamples: + - lang: cURL + source: 'curl -X GET ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/object-storages/6641ae21-e45d-4e03-8e70-661067152d1d/credentials/12345'' + -H ''Content-Type: application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" + -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' -H ''x-trace-id: + 123213''' + - lang: cntb CLI + source: cntb get user-credentials 6cdf5968-f9fe-4192-97c2-f349e813c5e8 6641ae21-e45d-4e03-8e70-661067152d1d + 12345 + patch: + description: Regenerates secret key of specified user for the a specific S3 + compatible object storages. + operationId: regenerateObjectStorageCredentials + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: type: string - name: - description: Role's name - example: infrastructure + style: simple + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + explode: false + in: path + name: userId + required: true + schema: type: string - admin: - description: Admin - example: true - type: boolean - accessAllResources: - description: Access All Resources - example: true - type: boolean - type: - description: Role type can be either `default` or `custom`. The `default` - roles cannot be modified or deleted. - example: custom + style: simple + - description: The identifier of the S3 object storage + example: d8417276-d2d9-43a9-a0a8-9a6fa6060246 + explode: false + in: path + name: objectStorageId + required: true + schema: type: string - permissions: + style: simple + - description: The ID of the object storage credential + example: 12345 + explode: false + in: path + name: credentialId + required: true + schema: + format: int64 + type: integer + style: simple + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/FindCredentialResponse' + description: The response will be a JSON object and contains object storage + S3 credentials. + security: + - bearer: [] + summary: Regenerates secret key of specified user for the S3 compatible object + storages. + tags: + - Users + x-codeSamples: + - lang: cURL + source: 'curl -X PATCH ''https://api.contabo.com/v1/users/6cdf5968-f9fe-4192-97c2-f349e813c5e8/object-storages/6641ae21-e45d-4e03-8e70-661067152d1d/credentials/12345'' + -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: 04e0f898-37b4-48bc-a794-1a57abe6aa31'' + -H ''x-trace-id: 123213''' + - lang: cntb CLI + source: cntb regenerate user-credentials 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + 6641ae21-e45d-4e03-8e70-661067152d1d 12345 + /v1/users/audits: + get: + description: List and filter the history about your users. + operationId: retrieveUserAuditsList + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ + type: string + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: + type: string + style: simple + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page + required: false + schema: + format: int64 + type: integer + style: form + - description: Number of elements per page. + example: 10 + explode: true + in: query + name: size + required: false + schema: + format: int64 + type: integer + style: form + - description: Specify fields and ordering (ASC for ascending, DESC for descending) + in following format `field:ASC|DESC`. + example: name:asc + explode: true + in: query + name: orderBy + required: false + schema: items: - $ref: '#/components/schemas/PermissionResponse' + type: string type: array - required: - - accessAllResources - - admin - - customerId - - name - - roleId - - tenantId - - type - type: object - UserResponse: - example: - owner: false - firstName: John - lastName: Doe - emailVerified: false - totp: false - roles: - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - tenantId: DE - customerId: "54321" - locale: de - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - email: john.doe@example.com - enabled: false - properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 + style: form + - description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + explode: true + in: query + name: userId + required: false + schema: type: string - userId: - description: The identifier of the user. - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + style: form + - description: The requestId of the API call which led to the change. + example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 + explode: true + in: query + name: requestId + required: false + schema: type: string - firstName: - description: The first name of the user. Users may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - user. - example: John - maxLength: 255 - minLength: 1 + style: form + - description: changedBy of the user which led to the change. + example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 + explode: true + in: query + name: changedBy + required: false + schema: type: string - lastName: - description: The last name of the user. Users may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - user. - example: Doe - maxLength: 255 - minLength: 1 + style: form + - description: Start of search time range. + example: 2021-01-01 + explode: true + in: query + name: startDate + required: false + schema: + format: date type: string - email: - description: The email of the user to which activation and forgot password - links are being sent to. There is a limit of 255 characters per email. - example: john.doe@example.com - maxLength: 255 - minLength: 1 + style: form + - description: End of search time range. + example: 2021-01-01 + explode: true + in: query + name: endDate + required: false + schema: + format: date type: string - emailVerified: - description: User email verification status. - example: false - type: boolean - enabled: - description: If uses is not enabled, he can't login and thus use services - any longer. - example: false - type: boolean - totp: - description: Enable or disable two-factor authentication (2FA) via time - based OTP. - example: false - type: boolean - locale: - description: The locale of the user. This can be `de-DE`, `de`, `en-US`, - `en` - enum: - - de-DE - - de - - en-US - - en - example: de + style: form + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListUserAuditResponse' + description: The response will be a JSON object and contains a paginated + list of users audits. + security: + - bearer: [] + summary: List history about your users (audit) + tags: + - Users Audits + x-codeSamples: + - lang: cURL + source: 'curl -X GET ''https://api.contabo.com/v1/users/audits'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31''' + - lang: cntb CLI + source: cntb history users + /v1/roles/audits: + get: + description: List and filter the history about your roles. + operationId: retrieveRoleAuditsList + parameters: + - description: '[Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) + to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) + to generate them manually.' + explode: false + in: header + name: x-request-id + required: true + schema: + example: 04e0f898-37b4-48bc-a794-1a57abe6aa31 + pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-5][0-9A-Fa-f]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string - roles: - description: The roles as list of `roleId`s of the user. + style: simple + - description: Identifier to trace group of requests. + explode: false + in: header + name: x-trace-id + required: false + schema: + type: string + style: simple + - description: Number of page to be fetched. + example: 1 + explode: true + in: query + name: page + required: false + schema: + format: int64 + type: integer + style: form + - description: Number of elements per page. + example: 10 + explode: true + in: query + name: size + required: false + schema: + format: int64 + type: integer + style: form + - description: Specify fields and ordering (ASC for ascending, DESC for descending) + in following format `field:ASC|DESC`. + example: name:asc + explode: true + in: query + name: orderBy + required: false + schema: items: - $ref: '#/components/schemas/RoleResponse' + type: string type: array - owner: - description: If user is owner he will have permissions to all API endpoints - and resources. Enabling this will superseed all role definitions and `accessAllResources`. - example: false - type: boolean + style: form + - description: The identifier of the role. + example: "12345" + explode: true + in: query + name: roleId + required: false + schema: + format: int64 + type: integer + style: form + - description: The requestId of the API call which led to the change. + example: D5FD9FAF-58C0-4406-8F46-F449B8E4FEC3 + explode: true + in: query + name: requestId + required: false + schema: + type: string + style: form + - description: changedBy of the user which led to the change. + example: 23cbb6d6-cb11-4330-bdff-7bb791df2e23 + explode: true + in: query + name: changedBy + required: false + schema: + type: string + style: form + - description: Start of search time range. + example: 2021-01-01 + explode: true + in: query + name: startDate + required: false + schema: + format: date + type: string + style: form + - description: End of search time range. + example: 2021-01-01 + explode: true + in: query + name: endDate + required: false + schema: + format: date + type: string + style: form + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListRoleAuditResponse' + description: The response will be a JSON object and contains a paginated + list of roles audits. + security: + - bearer: [] + summary: List history about your roles (audit) + tags: + - Roles Audits + x-codeSamples: + - lang: cURL + source: 'curl -X GET ''https://api.contabo.com/v1/roles/audits'' -H ''Content-Type: + application/json'' -H "Authorization: Bearer ${ACCESS_TOKEN}" -H ''x-request-id: + 04e0f898-37b4-48bc-a794-1a57abe6aa31''' + - lang: cntb CLI + source: cntb history roles +components: + schemas: + InstanceStartActionResponseData: + example: + instanceId: 12345 + tenantId: DE + customerId: "54321" + action: start + properties: + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + instanceId: + description: Compute instance / resource id + example: 12345 + format: int64 + type: integer + action: + description: Action that was triggered + example: start + type: string required: + - action - customerId - - email - - emailVerified - - enabled - - firstName - - lastName - - locale - - owner - - roles + - instanceId - tenantId - - totp - - userId type: object - Links: + SelfLinks: properties: self: description: Link to current resource. type: string - first: - description: Link to first page, if applicable. - type: string - previous: - description: Link to previous page, if applicable. - type: string - next: - description: Link to next page, if applicable. - type: string - last: - description: Link to last page, if applicable. - type: string required: - - first - - last - self type: object - ListUserResponse: + InstanceStartActionResponse: example: data: - - owner: false - firstName: John - lastName: Doe - emailVerified: false - totp: false - roles: - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom + - instanceId: 12345 tenantId: DE customerId: "54321" - locale: de - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - email: john.doe@example.com - enabled: false - - owner: false - firstName: John - lastName: Doe - emailVerified: false - totp: false - roles: - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom + action: start + - instanceId: 12345 tenantId: DE customerId: "54321" - locale: de - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - email: john.doe@example.com - enabled: false + action: start _links: - first: /v1/users?page=1 - next: /v1/users?page=19 - self: /v1/users/12345 - previous: /v1/users?page=21 - last: /v1/users?page=101 - _pagination: "" + self: /v1/compute/instances/12345/actions/start properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/UserResponse' + $ref: '#/components/schemas/InstanceStartActionResponseData' type: array _links: allOf: - - $ref: '#/components/schemas/Links' + - $ref: '#/components/schemas/SelfLinks' example: - first: /v1/users?page=1 - next: /v1/users?page=19 - self: /v1/users/12345 - previous: /v1/users?page=21 - last: /v1/users?page=101 + self: /v1/compute/instances/12345/actions/start required: - _links - - _pagination - data type: object - CreateUserRequest: - example: - firstName: John - lastName: Doe - totp: false - roles: - - 1 - - 2 - - 3 - - 4 - locale: de - email: john.doe@example.com - enabled: false - properties: - firstName: - description: The name of the user. Names may contain letters, numbers, colons, - dashes, and underscores. There is a limit of 255 characters per user. - example: John - maxLength: 255 - minLength: 1 - type: string - lastName: - description: The last name of the user. Users may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - user. - example: Doe - maxLength: 255 - minLength: 1 - type: string - email: - description: The email of the user to which activation and forgot password - links are being sent to. There is a limit of 255 characters per email. - example: john.doe@example.com - maxLength: 255 - minLength: 1 - type: string - enabled: - description: If user is not enabled, he can't login and thus use services - any longer. - example: false - type: boolean - totp: - description: Enable or disable two-factor authentication (2FA) via time - based OTP. - example: false - type: boolean - locale: - description: The locale of the user. This can be `de-DE`, `de`, `en-US`, - `en` - enum: - - de-DE - - de - - en-US - - en - example: de - type: string - roles: - description: The roles as list of `roleId`s of the user. - example: - - 1 - - 2 - - 3 - - 4 - items: - format: int64 - type: integer - type: array - required: - - email - - enabled - - locale - - totp - type: object - CreateUserResponseData: + InstanceRestartActionResponseData: example: + instanceId: 12345 tenantId: DE customerId: "54321" - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + action: start properties: tenantId: description: Your customer tenant id @@ -7438,284 +6945,202 @@ components: example: "54321" minLength: 1 type: string - userId: - description: User's id - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + instanceId: + description: Compute instance / resource id + example: 12345 + format: int64 + type: integer + action: + description: Action that was triggered + example: start type: string required: + - action - customerId + - instanceId - tenantId - - userId - type: object - SelfLinks: - properties: - self: - description: Link to current resource. - type: string - required: - - self type: object - CreateUserResponse: + InstanceRestartActionResponse: example: data: - - tenantId: DE + - instanceId: 12345 + tenantId: DE customerId: "54321" - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - - tenantId: DE + action: start + - instanceId: 12345 + tenantId: DE customerId: "54321" - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + action: start _links: - self: /v1/users/12345 + self: /v1/compute/instances/12345/actions/restart properties: data: items: - $ref: '#/components/schemas/CreateUserResponseData' + $ref: '#/components/schemas/InstanceRestartActionResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/users/12345 + self: /v1/compute/instances/12345/actions/restart required: - _links - data type: object - FindUserResponse: + InstanceStopActionResponseData: example: - data: - - owner: false - firstName: John - lastName: Doe - emailVerified: false - totp: false - roles: - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom + instanceId: 12345 + tenantId: DE + customerId: "54321" + action: start + properties: + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + instanceId: + description: Compute instance / resource id + example: 12345 + format: int64 + type: integer + action: + description: Action that was triggered + example: start + type: string + required: + - action + - customerId + - instanceId + - tenantId + type: object + InstanceStopActionResponse: + example: + data: + - instanceId: 12345 tenantId: DE customerId: "54321" - locale: de - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - email: john.doe@example.com - enabled: false - - owner: false - firstName: John - lastName: Doe - emailVerified: false - totp: false - roles: - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom + action: start + - instanceId: 12345 tenantId: DE customerId: "54321" - locale: de - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - email: john.doe@example.com - enabled: false + action: start _links: - self: /v1/users/12345 + self: /v1/compute/instances/12345/actions/stop properties: data: items: - $ref: '#/components/schemas/UserResponse' + $ref: '#/components/schemas/InstanceStopActionResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/users/12345 + self: /v1/compute/instances/12345/actions/stop required: - _links - data type: object - UpdateUserRequest: + InstanceShutdownActionResponseData: example: - firstName: John - lastName: Doe - totp: false - roles: - - 1 - - 2 - - 3 - - 4 - locale: de - email: john.doe@example.com - enabled: false + instanceId: 12345 + tenantId: DE + customerId: "54321" + action: start properties: - firstName: - description: The name of the user. Names may contain letters, numbers, colons, - dashes, and underscores. There is a limit of 255 characters per user. - example: John - maxLength: 255 - minLength: 1 - type: string - lastName: - description: The last name of the user. Users may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - user. - example: Doe - maxLength: 255 + tenantId: + description: Your customer tenant id + example: DE minLength: 1 type: string - email: - description: The email of the user to which activation and forgot password - links are being sent to. There is a limit of 255 characters per email. - example: john.doe@example.com - maxLength: 255 + customerId: + description: Your customer number + example: "54321" minLength: 1 type: string - enabled: - description: If user is not enabled, he can't login and thus use services - any longer. - example: false - type: boolean - totp: - description: Enable or disable two-factor authentication (2FA) via time - based OTP. - example: false - type: boolean - locale: - description: The locale of the user. This can be `de-DE`, `de`, `en-US`, - `en` - enum: - - de-DE - - de - - en-US - - en - example: de + instanceId: + description: Compute instance / resource id + example: 12345 + format: int64 + type: integer + action: + description: Action that was triggered + example: start type: string - roles: - description: The roles as list of `roleId`s of the user. - example: - - 1 - - 2 - - 3 - - 4 - items: - format: int64 - type: integer - type: array + required: + - action + - customerId + - instanceId + - tenantId type: object - UpdateUserResponse: + InstanceShutdownActionResponse: example: + data: + - instanceId: 12345 + tenantId: DE + customerId: "54321" + action: start + - instanceId: 12345 + tenantId: DE + customerId: "54321" + action: start _links: - self: /v1/users/12345 + self: /v1/compute/instances/12345/actions/shutdown properties: + data: + items: + $ref: '#/components/schemas/InstanceShutdownActionResponseData' + type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' - description: Links for easy navigation. example: - self: /v1/users/12345 + self: /v1/compute/instances/12345/actions/shutdown required: - _links + - data type: object - ClientResponse: + InstancesActionsRescueRequest: example: - clientId: DE-54321 + userData: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ + ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ + \ \n expire: False\n" + sshKeys: '[123, 125]' + rootPassword: 1 + properties: + rootPassword: + description: '`secretId` of the password to login into rescue system for + the `root` user.' + example: 1 + format: int64 + type: integer + sshKeys: + description: Array of `secretId`s of public SSH keys for logging into rescue + system as `root` user. + example: '[123, 125]' + items: + format: int64 + type: integer + type: array + userData: + description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize + during start of compute instance.' + example: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ + ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ + \ \n expire: False\n" + type: string + type: object + InstanceRescueActionResponseData: + example: + instanceId: 12345 tenantId: DE customerId: "54321" - id: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - secret: 7271e905-239e-4d15-a8c5-527743a58390 + action: start properties: tenantId: description: Your customer tenant id @@ -7727,59 +7152,86 @@ components: example: "54321" minLength: 1 type: string - id: - description: Client's id - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - type: string - clientId: - description: IDM client id - example: DE-54321 - type: string - secret: - description: IDM client secret - example: 7271e905-239e-4d15-a8c5-527743a58390 + instanceId: + description: Compute instance / resource id + example: 12345 + format: int64 + type: integer + action: + description: Action that was triggered + example: start type: string required: - - clientId + - action - customerId - - id - - secret + - instanceId - tenantId type: object - FindClientResponse: + InstanceRescueActionResponse: example: data: - - clientId: DE-54321 + - instanceId: 12345 tenantId: DE customerId: "54321" - id: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - secret: 7271e905-239e-4d15-a8c5-527743a58390 - - clientId: DE-54321 + action: start + - instanceId: 12345 tenantId: DE customerId: "54321" - id: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - secret: 7271e905-239e-4d15-a8c5-527743a58390 + action: start _links: - self: /v1/users/client + self: /v1/compute/instances/12345/actions/rescue properties: data: items: - $ref: '#/components/schemas/ClientResponse' + $ref: '#/components/schemas/InstanceRescueActionResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/users/client + self: /v1/compute/instances/12345/actions/rescue required: - _links - data type: object - ClientSecretResponse: + InstancesResetPasswordActionsRequest: + example: + userData: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ + ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ + \ \n expire: False\n" + sshKeys: '[123, 125]' + rootPassword: 1 + properties: + sshKeys: + description: Array of `secretId`s of public SSH keys for logging into as + `defaultUser` with administrator/root privileges. Applies to Linux/BSD + systems. Please refer to Secrets Management API. + example: '[123, 125]' + items: + format: int64 + type: integer + type: array + rootPassword: + description: '`secretId` of the password for the `defaultUser` with administrator/root + privileges. For Linux/BSD please use SSH, for Windows RDP. Please refer + to Secrets Management API.' + example: 1 + format: int64 + type: integer + userData: + description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize + during start of compute instance.' + example: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ + ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ + \ \n expire: False\n" + type: string + type: object + InstanceResetPasswordActionResponseData: example: + instanceId: 12345 tenantId: DE customerId: "54321" - secret: 7271e905-239e-4d15-a8c5-527743a58390 + action: start properties: tenantId: description: Your customer tenant id @@ -7791,994 +7243,930 @@ components: example: "54321" minLength: 1 type: string - secret: - description: IDM client secret - example: 7271e905-239e-4d15-a8c5-527743a58390 + instanceId: + description: Compute instance / resource id + example: 12345 + format: int64 + type: integer + action: + description: Action that was triggered + example: start type: string required: + - action - customerId - - secret + - instanceId - tenantId type: object - GenerateClientSecretResponse: + InstanceResetPasswordActionResponse: example: data: - - tenantId: DE + - instanceId: 12345 + tenantId: DE customerId: "54321" - secret: 7271e905-239e-4d15-a8c5-527743a58390 - - tenantId: DE + action: start + - instanceId: 12345 + tenantId: DE customerId: "54321" - secret: 7271e905-239e-4d15-a8c5-527743a58390 + action: start _links: - self: /v1/users/client/secret + self: /v1/compute/instances/12345/actions/resetPassword properties: data: items: - $ref: '#/components/schemas/ClientSecretResponse' + $ref: '#/components/schemas/InstanceResetPasswordActionResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/users/client/secret + self: /v1/compute/instances/12345/actions/resetPassword required: - _links - data type: object - UserIsPasswordSetResponse: + PaginationMeta: + properties: + size: + description: Number of elements per page. + example: 10 + type: number + totalElements: + description: Number of overall matched elements. + example: 100 + type: number + totalPages: + description: Overall number of pages. + example: 10 + type: number + page: + description: Current number of page. + example: 1 + type: number + required: + - page + - size + - totalElements + - totalPages + type: object + IpV4: example: - tenantId: DE - customerId: "54321" - isPasswordSet: false + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 + ip: + description: IP Address + example: 192.168.0.1 type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 + netmaskCidr: + description: Netmask CIDR + example: 19 + format: int32 + type: integer + gateway: + description: Gateway + example: 1.1.1.1 type: string - isPasswordSet: - description: Indicates if the user has set a password for his account - example: false - type: boolean required: - - customerId - - isPasswordSet - - tenantId + - gateway + - ip + - netmaskCidr type: object - FindUserIsPasswordSetResponse: + AdditionalIp: example: - data: - - tenantId: DE - customerId: "54321" - isPasswordSet: false - - tenantId: DE - customerId: "54321" - isPasswordSet: false - _links: - self: /v1/users/is-password-set + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 properties: - data: - items: - $ref: '#/components/schemas/UserIsPasswordSetResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/users/is-password-set + v4: + $ref: '#/components/schemas/IpV4' required: - - _links - - data + - v4 type: object - ListRoleResponse: + IpV6: example: - data: - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - _links: - first: /v1/role/{roleType}/?page=1 - next: /v1/role/{roleType}/?page=19 - self: /v1/role/{roleType}/12345 - previous: /v1/role/{roleType}/?page=21 - last: /v1/role/{roleType}?page=101 - _pagination: "" - properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. - data: - items: - $ref: '#/components/schemas/RoleResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' - example: - first: /v1/role/{roleType}/?page=1 - next: /v1/role/{roleType}/?page=19 - self: /v1/role/{roleType}/12345 - previous: /v1/role/{roleType}/?page=21 - last: /v1/role/{roleType}?page=101 - required: - - _links - - _pagination - - data - type: object - PermissionRequest: - example: - apiName: infrastructure - resources: - - 1 - - 2 - - 3 - actions: - - CREATE - - READ + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 properties: - apiName: - description: The name of the role. There is a limit of 255 characters per - role. - example: infrastructure - maxLength: 255 - minLength: 1 + ip: + description: IP Address + example: 1:2:3:4:5:6:7:8 + type: string + netmaskCidr: + description: Netmask CIDR + example: 64 + format: int32 + type: integer + gateway: + description: Gateway + example: 1:2:3:4:5:6:7:8 type: string - actions: - description: Action allowed for the API endpoint. Basically `CREATE` corresponds - to POST endpoints, `READ` to GET endpoints, `UPDATE` to PATCH / PUT endpoints - and `DELETE` to DELETE endpoints. - example: - - CREATE - - READ - items: - enum: - - CREATE - - READ - - UPDATE - - DELETE - type: string - type: array - resources: - description: The IDs of tags. Only if those tags are assgined to a resource - the user with that role will be able to access the resource. - example: - - 1 - - 2 - - 3 - items: - format: int64 - type: integer - type: array required: - - actions - - apiName + - gateway + - ip + - netmaskCidr type: object - CreateRoleRequest: + IpConfig: example: - permissions: - - apiName: infrastructure - resources: - - 1 - - 2 - - 3 - actions: - - CREATE - - READ - - apiName: infrastructure - resources: - - 1 - - 2 - - 3 - actions: - - CREATE - - READ - accessAllResources: false - name: infrastructure - admin: false + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 properties: - name: - description: The name of the role. There is a limit of 255 characters per - role. - example: infrastructure - maxLength: 255 - minLength: 1 - type: string - admin: - description: If user is admin he will have permissions to all API endpoints - and resources. Enabling this will superseed all role definitions and `accessAllResources`. - example: false - type: boolean - accessAllResources: - description: Allow access to all resources. This will superseed all assigned - resources in a role. - example: false - type: boolean - permissions: - items: - $ref: '#/components/schemas/PermissionRequest' - type: array + v4: + $ref: '#/components/schemas/IpV4' + v6: + $ref: '#/components/schemas/IpV6' required: - - accessAllResources - - admin - - name + - v4 + - v6 type: object - CreateRoleResponseData: + instanceStatus: + enum: + - provisioning + - uninstalled + - running + - stopped + - error + - installing + - unknown + - manual_provisioning + - product_not_available + - verification_required + - rescue + - pending_payment + - other + type: string + AddOnResponse: example: - roleId: 12345 - tenantId: DE - customerId: "54321" + quantity: 4 + id: 1431 properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 - type: string - roleId: - description: Role's id - example: 12345 + id: + description: Id of the Addon. Please refer to list [here](https://contabo.com/en/product-list/?show_ids=true). + example: 1431 + format: int64 + type: integer + quantity: + description: The number of Addons you wish to aquire. + example: 4 format: int64 type: integer required: - - customerId - - roleId - - tenantId + - id + - quantity type: object - CreateRoleResponse: + ListInstancesResponseData: example: - data: - - roleId: 12345 - tenantId: DE - customerId: "54321" - - roleId: 12345 - tenantId: DE - customerId: "54321" - _links: - self: /v1/roles/12345 - properties: - data: - items: - $ref: '#/components/schemas/CreateRoleResponseData' - type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/roles/12345 - required: - - _links - - data - type: object - FindRoleResponse: - example: - data: - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - - roleId: 12345 - permissions: - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - resources: - - tagId: 12345 - tagName: Web - - tagId: 12345 - tagName: Web - actions: - - CREATE - - READ - accessAllResources: true - tenantId: DE - customerId: "54321" - name: infrastructure - admin: true - type: custom - _links: - self: /v1/roles/12345 + cancelDate: 2021-06-03T00:00:00.000+0000 + displayName: VPS + regionName: European Union (Germany) + productName: VPS M + vHostNumber: 1001 + vHostName: m1000 + instanceId: 100 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + osType: Linux + defaultUser: root + sshKeys: + - 123 + - 125 + productType: ssd + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V5 + dataCenter: European Union (Germany) 1 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 + ramMb: 1024 + errorMessage: errorMessage + additionalIps: + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + diskMb: 2048 + macAddress: F2:65:50:F3:63:A1 + createdDate: 2021-06-03T06:27:12Z + cpuCores: 4 + vHostId: 73395 + tenantId: DE + name: vmd12345 + region: EU properties: - data: + tenantId: + description: Your customer tenant id + enum: + - DE + - INT + example: DE + minLength: 1 + type: string + customerId: + description: Customer ID + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + minLength: 1 + type: string + additionalIps: items: - $ref: '#/components/schemas/RoleResponse' + $ref: '#/components/schemas/AdditionalIp' type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/roles/12345 - required: - - _links - - data - type: object - UpdateRoleRequest: - example: - permissions: - - apiName: infrastructure - resources: - - 1 - - 2 - - 3 - actions: - - CREATE - - READ - - apiName: infrastructure - resources: - - 1 - - 2 - - 3 - actions: - - CREATE - - READ - accessAllResources: false - name: infrastructure - admin: false - properties: name: - description: The name of the role. There is a limit of 255 characters per - role. - example: infrastructure - maxLength: 255 - minLength: 1 + description: Instance Name + example: vmd12345 type: string - admin: - description: If user is admin he will have permissions to all API endpoints - and resources. Enabling this will superseed all role definitions and `accessAllResources`. - example: false - type: boolean - accessAllResources: - description: Allow access to all resources. This will superseed all assigned - resources in a role. - example: false - type: boolean - permissions: + displayName: + description: Instance display name + example: VPS + type: string + instanceId: + description: Instance ID + example: 100 + format: int64 + type: integer + dataCenter: + description: The data center where your Private Network is located + example: European Union (Germany) 1 + type: string + region: + description: Instance region where the compute instance should be located. + example: EU + type: string + regionName: + description: The name of the region where the instance is located. + example: European Union (Germany) + type: string + productId: + description: Product ID + example: V5 + type: string + imageId: + description: Image's id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + type: string + ipConfig: + $ref: '#/components/schemas/IpConfig' + macAddress: + description: MAC Address + example: F2:65:50:F3:63:A1 + type: string + ramMb: + description: Image RAM size in MB + example: 1024 + type: number + cpuCores: + description: CPU core count + example: 4 + format: int64 + type: integer + osType: + description: Type of operating system (OS) + example: Linux + type: string + diskMb: + description: Image Disk size in MB + example: 2048 + type: number + sshKeys: + description: Array of `secretId`s of public SSH keys for logging into as + `defaultUser` with administrator/root privileges. Applies to Linux/BSD + systems. Please refer to Secrets Management API. + example: + - 123 + - 125 items: - $ref: '#/components/schemas/PermissionRequest' + format: int64 + type: integer type: array - required: - - accessAllResources - - admin - - name - type: object - UpdateRoleResponse: - example: - _links: - self: /v1/roles/12345 - properties: - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - description: Links for easy navigation. - example: - self: /v1/roles/12345 - required: - - _links - type: object - ApiPermissionsResponse: - example: - apiName: /v1/compute/instances - actions: - - CREATE - - READ - properties: - apiName: - description: API endpoint. In order to get a list availbale api enpoints - please refer to the GET api-permissions endpoint. - example: /v1/compute/instances - type: string - actions: - description: Action allowed for the API endpoint. Basically `CREATE` corresponds - to POST endpoints, `READ` to GET endpoints, `UPDATE` to PATCH / PUT endpoints - and `DELETE` to DELETE endpoints. - example: - - CREATE - - READ - items: - enum: - - CREATE - - READ - - UPDATE - - DELETE - type: string - type: array - required: - - actions - - apiName - type: object - ListApiPermissionResponse: - example: - data: - - apiName: /v1/compute/instances - actions: - - CREATE - - READ - - apiName: /v1/compute/instances - actions: - - CREATE - - READ - _links: - first: /v1/roles/api-permissions?page=1 - previous: /v1/roles/api-permissions?page=2 - next: /v1/roles/api-permissions?page=3 - last: /v1/roles/api-permissions?page=10 - self: /v1/roles/api-permissions - properties: - data: - items: - $ref: '#/components/schemas/ApiPermissionsResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' - example: - first: /v1/roles/api-permissions?page=1 - previous: /v1/roles/api-permissions?page=2 - next: /v1/roles/api-permissions?page=3 - last: /v1/roles/api-permissions?page=10 - self: /v1/roles/api-permissions - required: - - _links - - data - type: object - CredentialData: - example: - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y - secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY - accessKey: AKIAIOSFODNN7EXAMPLE - displayName: Object Storage Test - tenantId: DE - customerId: "54321" - credentialId: 12345 - region: European Union (Germany) - properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 + createdDate: + description: The creation date for the instance + example: 2021-06-03T06:27:12Z + format: date-time type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 + cancelDate: + description: The date on which the instance will be cancelled + example: 2021-06-03 + format: date + maxLength: 10 + minLength: 0 + pattern: yyyy-mm-dd type: string - accessKey: - description: Access key ID. - example: AKIAIOSFODNN7EXAMPLE + status: + $ref: '#/components/schemas/instanceStatus' + vHostId: + description: ID of host system + example: 73395 + format: int64 + type: integer + vHostNumber: + description: Number of host system + example: 1001 + format: int64 + type: integer + vHostName: + description: Name of host system + example: m1000 type: string - secretKey: - description: Secret key ID. - example: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY + addOns: + items: + $ref: '#/components/schemas/AddOnResponse' + type: array + errorMessage: + description: Message in case of an error. type: string - objectStorageId: - description: Object Storage ID. - example: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y + productType: + description: Instance's category depending on Product Id + enum: + - hdd + - ssd + - vds + - nvme + example: ssd type: string - displayName: - description: Object Storage Name. - example: Object Storage Test + productName: + description: Instance's Product Name + example: VPS M type: string - region: - description: Object Storage Region. - example: European Union (Germany) + defaultUser: + description: Default user name created for login during (re-)installation + with administrative privileges. Allowed values for Linux/BSD are `admin` + (use sudo to apply administrative privileges like root) or `root`. Allowed + values for Windows are `admin` (has administrative privileges like administrator) + or `administrator`. + enum: + - root + - admin + - administrator + example: root type: string - credentialId: - description: Object Storage Credential ID - example: 12345 - type: number required: - - accessKey - - credentialId + - addOns + - additionalIps + - cancelDate + - cpuCores + - createdDate - customerId + - dataCenter + - diskMb - displayName - - objectStorageId + - imageId + - instanceId + - ipConfig + - macAddress + - name + - osType + - productId + - productName + - productType + - ramMb - region - - secretKey + - regionName + - sshKeys + - status - tenantId + - vHostId + - vHostName + - vHostNumber type: object - ListCredentialResponse: - example: - data: - - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y - secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY - accessKey: AKIAIOSFODNN7EXAMPLE - displayName: Object Storage Test - tenantId: DE - customerId: "54321" - credentialId: 12345 - region: European Union (Germany) - - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y - secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY - accessKey: AKIAIOSFODNN7EXAMPLE - displayName: Object Storage Test - tenantId: DE - customerId: "54321" - credentialId: 12345 - region: European Union (Germany) - _links: - first: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=1 - next: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=19 - self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials/12345 - previous: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=21 - last: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=101 - _pagination: "" + Links: properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. - data: - items: - $ref: '#/components/schemas/CredentialData' - type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' - example: - first: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=1 - next: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=19 - self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials/12345 - previous: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=21 - last: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=101 + self: + description: Link to current resource. + type: string + first: + description: Link to first page, if applicable. + type: string + previous: + description: Link to previous page, if applicable. + type: string + next: + description: Link to next page, if applicable. + type: string + last: + description: Link to last page, if applicable. + type: string required: - - _links - - _pagination - - data + - first + - last + - self type: object - FindCredentialResponse: + ListInstancesResponse: example: data: - - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y - secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY - accessKey: AKIAIOSFODNN7EXAMPLE - displayName: Object Storage Test - tenantId: DE - customerId: "54321" - credentialId: 12345 - region: European Union (Germany) - - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y - secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY - accessKey: AKIAIOSFODNN7EXAMPLE - displayName: Object Storage Test + - cancelDate: 2021-06-03T00:00:00.000+0000 + displayName: VPS + regionName: European Union (Germany) + productName: VPS M + vHostNumber: 1001 + vHostName: m1000 + instanceId: 100 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + osType: Linux + defaultUser: root + sshKeys: + - 123 + - 125 + productType: ssd + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V5 + dataCenter: European Union (Germany) 1 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 + ramMb: 1024 + errorMessage: errorMessage + additionalIps: + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + diskMb: 2048 + macAddress: F2:65:50:F3:63:A1 + createdDate: 2021-06-03T06:27:12Z + cpuCores: 4 + vHostId: 73395 tenantId: DE - customerId: "54321" - credentialId: 12345 - region: European Union (Germany) + name: vmd12345 + region: EU + - cancelDate: 2021-06-03T00:00:00.000+0000 + displayName: VPS + regionName: European Union (Germany) + productName: VPS M + vHostNumber: 1001 + vHostName: m1000 + instanceId: 100 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + osType: Linux + defaultUser: root + sshKeys: + - 123 + - 125 + productType: ssd + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V5 + dataCenter: European Union (Germany) 1 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 + ramMb: 1024 + errorMessage: errorMessage + additionalIps: + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + diskMb: 2048 + macAddress: F2:65:50:F3:63:A1 + createdDate: 2021-06-03T06:27:12Z + cpuCores: 4 + vHostId: 73395 + tenantId: DE + name: vmd12345 + region: EU _links: - self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/e3f0207c-f7fe-433a-92ab-39a9e976642d/credentials + first: /v1/compute/instances?page=1 + previous: /v1/compute/instances?page=19 + self: /v1/compute/instances?page=20 + next: /v1/compute/instances?page=21 + last: /v1/compute/instances?page=101 + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/CredentialData' + $ref: '#/components/schemas/ListInstancesResponseData' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/e3f0207c-f7fe-433a-92ab-39a9e976642d/credentials + first: /v1/compute/instances?page=1 + previous: /v1/compute/instances?page=19 + self: /v1/compute/instances?page=20 + next: /v1/compute/instances?page=21 + last: /v1/compute/instances?page=101 required: - _links + - _pagination - data type: object - UserAuditResponse: + InstanceResponse: example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + cancelDate: 2021-06-03T00:00:00.000+0000 + displayName: VPS + regionName: European Union (Germany) + productName: VPS M + vHostNumber: 1001 + vHostName: m1000 + instanceId: 100 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + osType: Linux + defaultUser: root + sshKeys: + - 123 + - 125 + productType: ssd + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V5 + dataCenter: European Union (Germany) 1 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 + ramMb: 1024 + errorMessage: errorMessage + additionalIps: + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + diskMb: 2048 + macAddress: F2:65:50:F3:63:A1 + createdDate: 2021-06-03T06:27:12Z + cpuCores: 4 + vHostId: 73395 tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + name: vmd12345 + region: EU properties: - id: - description: The identifier of the audit entry. - example: 12345 - format: int64 - type: integer - action: - description: Type of the action. - enum: - - CREATED - - UPDATED - - DELETED - example: CREATED - type: string - timestamp: - description: When the change took place. - example: 2021-03-30T11:35:06.177Z - format: date-time - type: string tenantId: - description: Customer tenant id + description: Your customer tenant id + enum: + - DE + - INT example: DE minLength: 1 type: string customerId: - description: Customer number - example: "54321" + description: Customer ID + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 minLength: 1 type: string - changedBy: - description: User ID - example: "54321" - minLength: 1 + additionalIps: + items: + $ref: '#/components/schemas/AdditionalIp' + type: array + name: + description: Instance Name + example: vmd12345 type: string - username: - description: Name of the user which led to the change. - example: John.Doe + displayName: + description: Instance display name + example: VPS type: string - requestId: - description: The requestId of the API call which led to the change. - example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + instanceId: + description: Instance ID + example: 100 + format: int64 + type: integer + dataCenter: + description: The data center where your Private Network is located + example: European Union (Germany) 1 type: string - traceId: - description: The traceId of the API call which led to the change. - example: 78E9A428-94E9-4A2A-92F5-26038C6884F + region: + description: Instance region where the compute instance should be located. + example: EU type: string - userId: - description: The identifier of the user - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + regionName: + description: The name of the region where the instance is located. + example: European Union (Germany) type: string - changes: - description: List of actual changes. - example: - prev: - name: test - new: - name: test1 - type: object - required: - - action - - changedBy - - customerId - - id - - requestId - - tenantId - - timestamp - - traceId - - userId - - username - type: object - ListUserAuditResponse: - example: - data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe - _links: - first: /v1/users/audits?page=2 - previous: /v1/users/audits?page=2 - next: /v1/users/audits?page=3 - last: /v1/users/audits?page=10 - self: /v1/users/audits - _pagination: "" - properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. - data: - items: - $ref: '#/components/schemas/UserAuditResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' - example: - first: /v1/users/audits?page=2 - previous: /v1/users/audits?page=2 - next: /v1/users/audits?page=3 - last: /v1/users/audits?page=10 - self: /v1/users/audits - required: - - _links - - _pagination - - data - type: object - RoleAuditResponse: - example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - roleId: 12345 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe - properties: - id: - description: The identifier of the audit entry. - example: 12345 + productId: + description: Product ID + example: V5 + type: string + imageId: + description: Image's id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + type: string + ipConfig: + $ref: '#/components/schemas/IpConfig' + macAddress: + description: MAC Address + example: F2:65:50:F3:63:A1 + type: string + ramMb: + description: Image RAM size in MB + example: 1024 + type: number + cpuCores: + description: CPU core count + example: 4 format: int64 type: integer - action: - description: Type of the action. - enum: - - CREATED - - UPDATED - - DELETED - example: CREATED + osType: + description: Type of operating system (OS) + example: Linux type: string - timestamp: - description: When the change took place. - example: 2021-03-30T11:35:06.177Z + diskMb: + description: Image Disk size in MB + example: 2048 + type: number + sshKeys: + description: Array of `secretId`s of public SSH keys for logging into as + `defaultUser` with administrator/root privileges. Applies to Linux/BSD + systems. Please refer to Secrets Management API. + example: + - 123 + - 125 + items: + format: int64 + type: integer + type: array + createdDate: + description: The creation date for the instance + example: 2021-06-03T06:27:12Z format: date-time type: string - tenantId: - description: Customer tenant id - example: DE - minLength: 1 + cancelDate: + description: The date on which the instance will be cancelled + example: 2021-06-03 + format: date + maxLength: 10 + minLength: 0 + pattern: yyyy-mm-dd type: string - customerId: - description: Customer number - example: "54321" - minLength: 1 + status: + $ref: '#/components/schemas/instanceStatus' + vHostId: + description: ID of host system + example: 73395 + format: int64 + type: integer + vHostNumber: + description: Number of host system + example: 1001 + format: int64 + type: integer + vHostName: + description: Name of host system + example: m1000 type: string - changedBy: - description: User ID - example: "54321" - minLength: 1 + addOns: + items: + $ref: '#/components/schemas/AddOnResponse' + type: array + errorMessage: + description: Message in case of an error. type: string - username: - description: Name of the user which led to the change. - example: John.Doe + productType: + description: Instance's category depending on Product Id + enum: + - hdd + - ssd + - vds + - nvme + example: ssd type: string - requestId: - description: The requestId of the API call which led to the change. - example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + productName: + description: Instance's Product Name + example: VPS M type: string - traceId: - description: The traceId of the API call which led to the change. - example: 78E9A428-94E9-4A2A-92F5-26038C6884F + defaultUser: + description: Default user name created for login during (re-)installation + with administrative privileges. Allowed values for Linux/BSD are `admin` + (use sudo to apply administrative privileges like root) or `root`. Allowed + values for Windows are `admin` (has administrative privileges like administrator) + or `administrator`. + enum: + - root + - admin + - administrator + example: root type: string - roleId: - description: The identifier of the role - example: 12345 - minimum: 0 - type: number - changes: - description: List of actual changes. - example: - prev: - name: test - new: - name: test1 - type: object required: - - action - - changedBy + - addOns + - additionalIps + - cancelDate + - cpuCores + - createdDate - customerId - - id - - requestId - - roleId - - tenantId - - timestamp - - traceId - - username - type: object - ListRoleAuditResponse: - example: - data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - roleId: 12345 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - roleId: 12345 + - dataCenter + - diskMb + - displayName + - imageId + - instanceId + - ipConfig + - macAddress + - name + - osType + - productId + - productName + - productType + - ramMb + - region + - regionName + - sshKeys + - status + - tenantId + - vHostId + - vHostName + - vHostNumber + type: object + FindInstanceResponse: + example: + data: + - cancelDate: 2021-06-03T00:00:00.000+0000 + displayName: VPS + regionName: European Union (Germany) + productName: VPS M + vHostNumber: 1001 + vHostName: m1000 + instanceId: 100 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + osType: Linux + defaultUser: root + sshKeys: + - 123 + - 125 + productType: ssd + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V5 + dataCenter: European Union (Germany) 1 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 + ramMb: 1024 + errorMessage: errorMessage + additionalIps: + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + diskMb: 2048 + macAddress: F2:65:50:F3:63:A1 + createdDate: 2021-06-03T06:27:12Z + cpuCores: 4 + vHostId: 73395 tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + name: vmd12345 + region: EU + - cancelDate: 2021-06-03T00:00:00.000+0000 + displayName: VPS + regionName: European Union (Germany) + productName: VPS M + vHostNumber: 1001 + vHostName: m1000 + instanceId: 100 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + osType: Linux + defaultUser: root + sshKeys: + - 123 + - 125 + productType: ssd + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V5 + dataCenter: European Union (Germany) 1 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 + ramMb: 1024 + errorMessage: errorMessage + additionalIps: + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + diskMb: 2048 + macAddress: F2:65:50:F3:63:A1 + createdDate: 2021-06-03T06:27:12Z + cpuCores: 4 + vHostId: 73395 + tenantId: DE + name: vmd12345 + region: EU _links: - first: /v1/roles/audits?page=2 - previous: /v1/roles/audits?page=2 - next: /v1/roles/audits?page=3 - last: /v1/roles/audits?page=10 - self: /v1/roles/audits + self: /v1/compute/instances/100 properties: data: items: - $ref: '#/components/schemas/RoleAuditResponse' + $ref: '#/components/schemas/InstanceResponse' type: array _links: allOf: - - $ref: '#/components/schemas/Links' + - $ref: '#/components/schemas/SelfLinks' example: - first: /v1/roles/audits?page=2 - previous: /v1/roles/audits?page=2 - next: /v1/roles/audits?page=3 - last: /v1/roles/audits?page=10 - self: /v1/roles/audits + self: /v1/compute/instances/100 required: - _links - data type: object - AutoScalingTypeResponse: + PatchInstanceRequest: + example: + displayName: VPS properties: - state: - description: State of the autoscaling for the current object storage. - enum: - - enabled - - disabled - - error - example: enabled - type: string - sizeLimitTB: - description: Autoscaling size limit for the current object storage. - example: 1 - format: double - type: number - errorMessage: - description: Error message + displayName: + description: The display name of the instance + example: VPS + maxLength: 255 type: string - required: - - sizeLimitTB - - state type: object - ObjectStorageResponse: + PatchInstanceResponseData: example: - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + instanceId: 12345 createdDate: 2021-06-02T12:32:03.363Z tenantId: DE customerId: "54321" - region: European Union (Germany) - status: READY properties: tenantId: description: Your customer tenant id @@ -8790,587 +8178,527 @@ components: example: "54321" minLength: 1 type: string - objectStorageId: - description: Your object storage id - example: b943b25a-c8b5-4570-9135-4bbaa7615b81 - minLength: 1 - type: string + instanceId: + description: Instance's id + example: 12345 + format: int64 + type: integer createdDate: - description: Creation date for object storage. + description: Creation date of the instance example: 2021-06-02T12:32:03.363Z format: date-time type: string - cancelDate: - description: Cancellation date for object storage. - example: 2021-06-02 - format: date - type: string - autoScaling: + required: + - createdDate + - customerId + - instanceId + - tenantId + type: object + PatchInstanceResponse: + example: + data: + - instanceId: 12345 + createdDate: 2021-06-02T12:32:03.363Z + tenantId: DE + customerId: "54321" + - instanceId: 12345 + createdDate: 2021-06-02T12:32:03.363Z + tenantId: DE + customerId: "54321" + _links: + self: /v1/compute/instances/12345 + properties: + data: + items: + $ref: '#/components/schemas/PatchInstanceResponseData' + type: array + _links: allOf: - - $ref: '#/components/schemas/AutoScalingTypeResponse' - description: Autoscaling settings - dataCenter: - description: Data center your object storage is located - example: EU - minLength: 1 - type: string - totalPurchasedSpaceTB: - description: Amount of purchased / requested object storage in TB. - example: 6.25 - format: double - type: number - s3Url: - description: S3 URL to connect to your S3 compatible object storage - example: eu1-s3.contabo.com - type: string - s3TenantId: - description: Your S3 tenantId. Only required for public sharing. - example: 2cd2e5e1444a41b0bed16c6410ecaa84 + - $ref: '#/components/schemas/SelfLinks' + example: + self: /v1/compute/instances/12345 + required: + - _links + - data + type: object + ReinstallInstanceRequest: + example: + imageId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + userData: |- + #cloud-config + user: admin + timezone: Europe/Berlin + chpasswd: + expire: False + defaultUser: root + sshKeys: '[123, 125]' + applicationId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + rootPassword: 1 + properties: + imageId: + description: ImageId to be used to setup the compute instance. + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 type: string - status: - description: The object storage status + sshKeys: + description: Array of `secretId`s of public SSH keys for logging into as + `defaultUser` with administrator/root privileges. Applies to Linux/BSD + systems. Please refer to Secrets Management API. + example: '[123, 125]' + items: + format: int64 + type: integer + type: array + rootPassword: + description: '`secretId` of the password for the `defaultUser` with administrator/root + privileges. For Linux/BSD please use SSH, for Windows RDP. Please refer + to Secrets Management API.' + example: 1 + format: int64 + type: integer + userData: + description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize + during start of compute instance.' + example: |- + #cloud-config + user: admin + timezone: Europe/Berlin + chpasswd: + expire: False + type: string + defaultUser: + default: admin + description: Default user name created for login during (re-)installation + with administrative privileges. Allowed values for Linux/BSD are `admin` + (use sudo to apply administrative privileges like root) or `root`. Allowed + values for Windows are `admin` (has administrative privileges like administrator) + or `administrator`. enum: - - READY - - PROVISIONING - - UPGRADING - - CANCELLED - - ERROR - - ENABLED - - DISABLED - - MANUAL_PROVISIONING - - PRODUCT_NOT_AVAILABLE - - LIMIT_EXCEEDED - - VERIFICATION_REQUIRED - - COMPLETED - - ORDER_PROCESSING - - PENDING_PAYMENT - - UNKNOWN - example: READY + - root + - admin + - administrator + example: root type: string - region: - description: The region where your object storage is located - example: European Union (Germany) + applicationId: + description: Application ID + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 type: string - displayName: - description: Display name for object storage. - example: Object storage 1 - maxLength: 255 + required: + - imageId + type: object + ReinstallInstanceResponseData: + example: + instanceId: 12345 + createdDate: 2021-06-02T12:32:03.363Z + tenantId: DE + customerId: "54321" + properties: + tenantId: + description: Your customer tenant id + example: DE minLength: 1 type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + instanceId: + description: Instance's id + example: 12345 + format: int64 + type: integer + createdDate: + description: Creation date for instance + example: 2021-06-02T12:32:03.363Z + format: date-time + type: string required: - - autoScaling - - cancelDate - createdDate - customerId - - dataCenter - - displayName - - objectStorageId - - region - - s3TenantId - - s3Url - - status + - instanceId - tenantId - - totalPurchasedSpaceTB type: object - ListObjectStorageResponse: + ReinstallInstanceResponse: example: data: - - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + - instanceId: 12345 createdDate: 2021-06-02T12:32:03.363Z tenantId: DE customerId: "54321" - region: European Union (Germany) - status: READY - - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + - instanceId: 12345 createdDate: 2021-06-02T12:32:03.363Z tenantId: DE customerId: "54321" - region: European Union (Germany) - status: READY _links: - first: /v1/object-storages?size=10 - previous: /v1/object-storages?page=1&size=10 - next: /v1/object-storages?page=3&size=10 - last: /v1/object-storages?page=5&size=10 - self: /v1/object-storages - _pagination: "" + self: /v1/compute/instances/12345 properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/ObjectStorageResponse' + $ref: '#/components/schemas/ReinstallInstanceResponseData' type: array _links: allOf: - - $ref: '#/components/schemas/Links' + - $ref: '#/components/schemas/SelfLinks' example: - first: /v1/object-storages?size=10 - previous: /v1/object-storages?page=1&size=10 - next: /v1/object-storages?page=3&size=10 - last: /v1/object-storages?page=5&size=10 - self: /v1/object-storages + self: /v1/compute/instances/12345 required: - _links - - _pagination - data type: object - DataCenterResponse: - example: - s3Url: eu1-s3.contabo.com - capabilities: - - VPS - - Object-Storage - regionSlug: EU - regionName: European Union (Germany) - name: European Union (Germany) 1 - tenantId: DE - customerId: "54321" - slug: EU1 + ExtraStorageRequest: properties: - name: - description: Name of the data center - example: European Union (Germany) 1 - minLength: 1 - type: string - slug: - description: Slug of the data center - example: EU1 - minLength: 1 - type: string - capabilities: - example: - - VPS - - Object-Storage + ssd: + description: Specify the size in TB and the quantity + items: + type: string + type: array + nvme: + description: Specify the size in TB and the quantity items: - enum: - - VPS - - VDS - - Object-Storage - - Private-Networking type: string type: array - s3Url: - description: S3 URL of the data center - example: eu1-s3.contabo.com - minLength: 1 - type: string - regionName: - description: Name of the region - example: European Union (Germany) - minLength: 1 - type: string - regionSlug: - description: Slug of the region - example: EU - minLength: 1 - type: string - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 - type: string - required: - - capabilities - - customerId - - name - - regionName - - regionSlug - - s3Url - - slug - - tenantId type: object - ListDataCenterResponse: - example: - data: - - s3Url: eu1-s3.contabo.com - capabilities: - - VPS - - Object-Storage - regionSlug: EU - regionName: European Union (Germany) - name: European Union (Germany) 1 - tenantId: DE - customerId: "54321" - slug: EU1 - - s3Url: eu1-s3.contabo.com - capabilities: - - VPS - - Object-Storage - regionSlug: EU - regionName: European Union (Germany) - name: European Union (Germany) 1 - tenantId: DE - customerId: "54321" - slug: EU1 - _links: - first: /v1/data-centers?page=1 - previous: /v1/data-centers?page=19 - self: /v1/data-centers/12345 - next: /v1/data-centers?page=21 - last: /v1/data-centers?page=101 - _pagination: "" + AddOnRequest: properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. - data: - items: - $ref: '#/components/schemas/DataCenterResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' - example: - first: /v1/data-centers?page=1 - previous: /v1/data-centers?page=19 - self: /v1/data-centers/12345 - next: /v1/data-centers?page=21 - last: /v1/data-centers?page=101 + id: + description: Id of the Addon. Please refer to list [here](https://contabo.com/en/product-list/?show_ids=true). + example: 1019 + format: int64 + type: integer + quantity: + description: The number of Addons you wish to aquire. + example: 4 + format: int64 + type: integer required: - - _links - - _pagination - - data + - id + - quantity type: object - AutoScalingTypeRequest: + CreateInstanceAddons: properties: - state: - description: State of the autoscaling for the current object storage. - enum: - - enabled - - disabled - example: enabled - type: string - sizeLimitTB: - description: Autoscaling size limit for the current object storage. - example: 1 - format: double - type: number - required: - - sizeLimitTB - - state + privateNetworking: + description: Set this attribute if you want to upgrade your instance with + the Private Networking addon. Please provide an empty object for the + time being as value. There will be more configuration possible in the + future. + example: {} + type: object + additionalIps: + description: Set this attribute if you want to upgrade your instance with + the Additional IPs addon. Please provide an empty object for the time + being as value. There will be more configuration possible in the future. + example: {} + type: object + extraStorage: + allOf: + - $ref: '#/components/schemas/ExtraStorageRequest' + description: Set this attribute if you want to upgrade your instance with + the Extra Storage addon. + example: {} + customImage: + description: Set this attribute if you want to upgrade your instance with + the Custom Images addon. Please provide an empty object for the time + being as value. There will be more configuration possible in the future. + example: {} + type: object + addonsIds: + items: + $ref: '#/components/schemas/AddOnRequest' + type: array type: object - CreateObjectStorageRequest: + CreateInstanceRequest: example: - autoScaling: "" - displayName: Object storage 1 + license: PleskHost + period: 6 + imageId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + userData: |- + #cloud-config + user: admin + timezone: Europe/Berlin + chpasswd: + expire: False + productId: V45 + displayName: VPS + addOns: + privateNetworking: {} + additionalIps: {} + extraStorage: {} + customImage: {} + defaultUser: root + sshKeys: '[123, 125]' region: EU - totalPurchasedSpaceTB: 6 + applicationId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + rootPassword: 1 properties: + imageId: + default: afecbb85-e2fc-46f0-9684-b46b1faf00bb + description: ImageId to be used to setup the compute instance. Default is + Ubuntu 22.04 + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + type: string + productId: + default: V45 + description: Default is V45 + example: V45 + minLength: 1 + type: string region: default: EU - description: 'Region where the object storage should be located. Default - is EU. Available regions: EU, US-central, SIN' + description: Instance Region where the compute instance should be located. + Default is EU + enum: + - EU + - US-central + - US-east + - US-west + - SIN + - UK + - AUS + - JPN example: EU minLength: 1 type: string - autoScaling: - allOf: - - $ref: '#/components/schemas/AutoScalingTypeRequest' - description: Autoscaling settings - totalPurchasedSpaceTB: - description: Amount of purchased / requested object storage in TB. + sshKeys: + description: Array of `secretId`s of public SSH keys for logging into as + `defaultUser` with administrator/root privileges. Applies to Linux/BSD + systems. Please refer to Secrets Management API. + example: '[123, 125]' + items: + format: int64 + type: integer + type: array + rootPassword: + description: '`secretId` of the password for the `defaultUser` with administrator/root + privileges. For Linux/BSD please use SSH, for Windows RDP. Please refer + to Secrets Management API.' + example: 1 + format: int64 + type: integer + userData: + description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize + during start of compute instance.' + example: |- + #cloud-config + user: admin + timezone: Europe/Berlin + chpasswd: + expire: False + type: string + license: + description: Additional licence in order to enhance your chosen product, + mainly needed for software licenses on your product (not needed for windows). + enum: + - cPanel5 + - cPanel30 + - cPanel50 + - cPanel100 + - cPanel150 + - cPanel200 + - cPanel250 + - cPanel300 + - cPanel350 + - cPanel400 + - cPanel450 + - cPanel500 + - cPanel550 + - cPanel600 + - cPanel650 + - cPanel700 + - cPanel750 + - cPanel800 + - cPanel850 + - cPanel900 + - cPanel950 + - cPanel1000 + - PleskAdmin + - PleskHost + - PleskPro + example: PleskHost + type: string + period: + default: 1 + description: 'Initial contract period in months. Available periods are: + 1, 3, 6 and 12 months. Default to 1 month' example: 6 - format: double - type: number + format: int64 + type: integer displayName: - description: Display name helps to differentiate between object storages, - especially if they are in the same region. If display name is not provided, - it will be generated. Display name can be changed any time. - example: Object storage 1 + description: The display name of the instance + example: VPS maxLength: 255 - minLength: 1 type: string - required: - - region - - totalPurchasedSpaceTB - type: object - CreateObjectStorageResponseData: - example: - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - usedSpacePercentage: 100 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 - createdDate: 2021-06-02T12:32:03.363Z - usedSpaceTB: 4 - tenantId: DE - customerId: "54321" - region: European Union (Germany) - status: READY - properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 + defaultUser: + default: admin + description: Default user name created for login during (re-)installation + with administrative privileges. Allowed values for Linux/BSD are `admin` + (use sudo to apply administrative privileges like root) or `root`. Allowed + values for Windows are `admin` (has administrative privileges like administrator) + or `administrator`. + enum: + - root + - admin + - administrator + example: root + type: string + addOns: + allOf: + - $ref: '#/components/schemas/CreateInstanceAddons' + description: Set attributes in the addons object for the corresponding ones + that need to be added to the instance + example: + privateNetworking: {} + additionalIps: {} + extraStorage: {} + customImage: {} + applicationId: + description: Application ID + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + type: string + required: + - period + type: object + CreateInstanceResponseData: + example: + instanceId: 12345 + createdDate: 2021-06-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V45 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 + tenantId: DE + customerId: "54321" + osType: Linux + sshKeys: + - 123 + - 125 + region: EU + properties: + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 type: string customerId: description: Your customer number example: "54321" minLength: 1 type: string - objectStorageId: - description: Your object storage id - example: b943b25a-c8b5-4570-9135-4bbaa7615b81 - minLength: 1 - type: string + instanceId: + description: Instance's id + example: 12345 + format: int64 + type: integer createdDate: - description: Creation date for object storage. + description: Creation date for instance example: 2021-06-02T12:32:03.363Z format: date-time type: string - cancelDate: - description: Cancellation date for object storage. - example: 2021-06-02 - format: date - type: string - autoScaling: - allOf: - - $ref: '#/components/schemas/AutoScalingTypeResponse' - description: Autoscaling settings - dataCenter: - description: The data center of the storage - example: EU - minLength: 1 - type: string - totalPurchasedSpaceTB: - description: Amount of purchased / requested object storage in TB. - example: 6.25 - format: double - type: number - usedSpaceTB: - description: Currently used space in TB. - example: 4 - format: double - type: number - usedSpacePercentage: - description: Currently used space in percentage. - example: 100 - format: double - maximum: 100 - minimum: 0 - type: number - s3Url: - description: S3 URL to connect to your S3 compatible object storage - example: eu1-s3.contabo.com - type: string - s3TenantId: - description: Your S3 tenantId. Only required for public sharing. - example: 2cd2e5e1444a41b0bed16c6410ecaa84 + imageId: + description: Image's id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d type: string - status: - description: The object storage status - enum: - - READY - - PROVISIONING - - UPGRADING - - CANCELLED - - ERROR - - ENABLED - - DISABLED - - MANUAL_PROVISIONING - - PRODUCT_NOT_AVAILABLE - - LIMIT_EXCEEDED - - VERIFICATION_REQUIRED - - COMPLETED - - ORDER_PROCESSING - - PENDING_PAYMENT - - UNKNOWN - example: READY - minLength: 1 + productId: + description: Product ID + example: V45 type: string region: - description: The region where your object storage is located - example: European Union (Germany) + description: Instance Region where the compute instance should be located. + example: EU type: string - displayName: - description: Display name for object storage. - example: Object storage 1 - maxLength: 255 - minLength: 1 + addOns: + items: + $ref: '#/components/schemas/AddOnResponse' + type: array + osType: + description: Type of operating system (OS) + example: Linux type: string + status: + $ref: '#/components/schemas/instanceStatus' + sshKeys: + description: Array of `secretId`s of public SSH keys for logging into as + `defaultUser` with administrator/root privileges. Applies to Linux/BSD + systems. Please refer to Secrets Management API. + example: + - 123 + - 125 + items: + format: int64 + type: integer + type: array required: - - autoScaling - - cancelDate + - addOns - createdDate - customerId - - dataCenter - - displayName - - objectStorageId + - imageId + - instanceId + - osType + - productId - region - - s3TenantId - - s3Url + - sshKeys - status - tenantId - - totalPurchasedSpaceTB - - usedSpacePercentage - - usedSpaceTB type: object - CreateObjectStorageResponse: + CreateInstanceResponse: example: data: - - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - usedSpacePercentage: 100 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + - instanceId: 12345 createdDate: 2021-06-02T12:32:03.363Z - usedSpaceTB: 4 + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V45 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 tenantId: DE customerId: "54321" - region: European Union (Germany) - status: READY - - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - usedSpacePercentage: 100 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + osType: Linux + sshKeys: + - 123 + - 125 + region: EU + - instanceId: 12345 createdDate: 2021-06-02T12:32:03.363Z - usedSpaceTB: 4 + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + productId: V45 + addOns: + - quantity: 4 + id: 1431 + - quantity: 4 + id: 1431 tenantId: DE customerId: "54321" - region: European Union (Germany) - status: READY + osType: Linux + sshKeys: + - 123 + - 125 + region: EU _links: - self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 + self: /v1/compute/instances/12345 properties: data: items: - $ref: '#/components/schemas/CreateObjectStorageResponseData' + $ref: '#/components/schemas/CreateInstanceResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 + self: /v1/compute/instances/12345 required: - _links - data type: object - FindObjectStorageResponse: + CancelInstanceResponseData: example: - data: - - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 - createdDate: 2021-06-02T12:32:03.363Z - tenantId: DE - customerId: "54321" - region: European Union (Germany) - status: READY - - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 - cancelDate: 2021-06-02T00:00:00.000+0000 - s3Url: eu1-s3.contabo.com - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 - totalPurchasedSpaceTB: 6.25 - s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 - createdDate: 2021-06-02T12:32:03.363Z - tenantId: DE - customerId: "54321" - region: European Union (Germany) - status: READY - _links: - self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 - properties: - data: - items: - $ref: '#/components/schemas/ObjectStorageResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 - required: - - _links - - data - type: object - UpgradeAutoScalingType: - properties: - state: - description: State of the autoscaling for the current object storage. - enum: - - enabled - - disabled - example: enabled - type: string - sizeLimitTB: - description: Autoscaling size limit for the current object storage. - example: 6 - format: double - type: number - type: object - UpgradeObjectStorageRequest: - example: - autoScaling: "" - totalPurchasedSpaceTB: 8 - properties: - autoScaling: - allOf: - - $ref: '#/components/schemas/UpgradeAutoScalingType' - description: New monthly object storage size limit for autoscaling if enabled. - totalPurchasedSpaceTB: - description: New total object storage limit. If this number is larger than - before you will also be billed for the added storage space. No downgrade - possible. - example: 8 - format: double - type: number - type: object - UpgradeObjectStorageResponseData: - example: - objectStorageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - s3Url: eu1-s3.contabo.com - createdDate: 2021-06-02T12:32:03.363Z - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 + cancelDate: 2021-06-03T00:00:00.000+0000 + instanceId: 12345 tenantId: DE customerId: "54321" - region: European Union (Germany) - totalPurchasedSpaceTB: 6 - status: READY properties: tenantId: description: Your customer tenant id @@ -9382,494 +8710,651 @@ components: example: "54321" minLength: 1 type: string - objectStorageId: - description: Object storage id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - minLength: 1 - type: string - createdDate: - description: Creation date for object storage. - example: 2021-06-02T12:32:03.363Z - type: string - dataCenter: - description: Data center of the object storage. - example: EU - type: string - autoScaling: - allOf: - - $ref: '#/components/schemas/AutoScalingTypeResponse' - description: The autoscaling limit of the object storage. - s3Url: - description: S3 URL to connect to your S3 compatible object storage - example: eu1-s3.contabo.com - type: string - status: - description: The object storage status - enum: - - READY - - PROVISIONING - - UPGRADING - - CANCELLED - - ERROR - - ENABLED - - DISABLED - - MANUAL_PROVISIONING - - PRODUCT_NOT_AVAILABLE - - LIMIT_EXCEEDED - - VERIFICATION_REQUIRED - - COMPLETED - - ORDER_PROCESSING - - PENDING_PAYMENT - - UNKNOWN - example: READY - type: string - totalPurchasedSpaceTB: - description: Total purchased object storage space in TB. - example: 6 - format: double - type: number - region: - description: The region where your object storage is located - example: European Union (Germany) - type: string - displayName: - description: Display name for object storage. - example: Object storage 1 - maxLength: 255 - minLength: 1 + instanceId: + description: Instance's id + example: 12345 + format: int64 + type: integer + cancelDate: + description: The date on which the instance will be cancelled + example: 2021-06-03 + format: date type: string required: - - autoScaling - - createdDate + - cancelDate - customerId - - dataCenter - - displayName - - objectStorageId - - region - - s3Url - - status + - instanceId - tenantId - - totalPurchasedSpaceTB type: object - UpgradeObjectStorageResponse: + CancelInstanceResponse: example: data: - - objectStorageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - s3Url: eu1-s3.contabo.com - createdDate: 2021-06-02T12:32:03.363Z - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 + - cancelDate: 2021-06-03T00:00:00.000+0000 + instanceId: 12345 tenantId: DE customerId: "54321" - region: European Union (Germany) - totalPurchasedSpaceTB: 6 - status: READY - - objectStorageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - s3Url: eu1-s3.contabo.com - createdDate: 2021-06-02T12:32:03.363Z - autoScaling: "" - dataCenter: EU - displayName: Object storage 1 + - cancelDate: 2021-06-03T00:00:00.000+0000 + instanceId: 12345 tenantId: DE customerId: "54321" - region: European Union (Germany) - totalPurchasedSpaceTB: 6 - status: READY _links: - self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + self: /v1/compute/instances/12345 properties: + data: + items: + $ref: '#/components/schemas/CancelInstanceResponseData' + type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - data: - items: - $ref: '#/components/schemas/UpgradeObjectStorageResponseData' - type: array + self: /v1/compute/instances/12345 required: - _links - data type: object - ObjectStoragesStatsResponseData: + FirewallingUpgradeRequest: + properties: + assignFirewalls: + description: List of IDs of firewalls the upgraded instance should be assigned + to immediately. If the list is empty or this property is not provided + the instance will be assigned to your current default firewall. + items: + type: string + type: array + type: object + PrivateNetworkingUpgradeRequest: + properties: {} + type: object + AddOnQuantityRequest: + properties: + quantity: + description: The number of Addons you wish to aquire. + example: 4 + format: int64 + type: integer + required: + - quantity + type: object + UpgradeInstanceRequest: example: - usedSpaceTB: 4 - numberOfObjects: 2 - usedSpacePercentage: 100 + privateNetworking: {} + properties: + privateNetworking: + allOf: + - $ref: '#/components/schemas/PrivateNetworkingUpgradeRequest' + description: Set this attribute if you want to upgrade your instance with + the Private Networking addon. Please provide an empty object for the time + being as value. There will be more configuration possible in the future. + example: {} + type: object + InstancesActionsAuditResponse: + example: + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe properties: + id: + description: The ID of the audit entry. + example: 12345 + format: int64 + type: integer + action: + description: Type of the action. + enum: + - CREATED + - UPDATED + - DELETED + example: CREATED + type: string + timestamp: + description: When the change took place. + example: 2021-03-30T11:35:06.177Z + format: date-time + type: string tenantId: - description: Your customer tenant id + description: Customer tenant id example: DE minLength: 1 type: string customerId: - description: Your customer number + description: Customer ID example: "54321" minLength: 1 type: string - usedSpaceTB: - description: Currently used space in TB. - example: 4 - format: double - type: number - usedSpacePercentage: - description: Currently used space in percentage. - example: 100 - format: double - maximum: 100 - minimum: 0 - type: number - numberOfObjects: - description: Number of all objects (i.e. files and folders) in object storage. - example: 2 + changedBy: + description: Id of user who performed the change + example: c4c800ff-e524-47dd-9543-71dfc8b91113 + minLength: 1 + type: string + username: + description: Name of the user which led to the change. + example: John.Doe + type: string + requestId: + description: The requestId of the API call which led to the change. + example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + type: string + traceId: + description: The traceId of the API call which led to the change. + example: 78E9A428-94E9-4A2A-92F5-26038C6884F + type: string + instanceId: + description: The identifier of the instancesActions + example: 12345 format: int64 + minimum: 0 type: integer + changes: + description: List of actual changes. + example: + prev: + name: test + new: + name: test1 + type: object required: + - action + - changedBy - customerId - - numberOfObjects + - id + - instanceId + - requestId - tenantId - - usedSpacePercentage - - usedSpaceTB + - timestamp + - traceId + - username type: object - ObjectStoragesStatsResponse: + ListInstancesActionsAuditResponse: example: data: - - usedSpaceTB: 4 - numberOfObjects: 2 - usedSpacePercentage: 100 + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - - usedSpaceTB: 4 - numberOfObjects: 2 - usedSpacePercentage: 100 + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe _links: - self: /v1/object-storages/stats/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 + first: /v1/compute/instances/actions/audits?page=2 + previous: /v1/compute/instances/actions/audits?page=2 + next: /v1/compute/instances/actions/audits?page=3 + last: /v1/compute/instances/actions/audits?page=10 + self: /v1/compute/instances/actions/audits + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/ObjectStoragesStatsResponseData' + $ref: '#/components/schemas/InstancesActionsAuditResponse' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/object-storages/stats/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 + first: /v1/compute/instances/actions/audits?page=2 + previous: /v1/compute/instances/actions/audits?page=2 + next: /v1/compute/instances/actions/audits?page=3 + last: /v1/compute/instances/actions/audits?page=10 + self: /v1/compute/instances/actions/audits required: - _links + - _pagination - data type: object - CancelObjectStorageResponseData: + InstancesAuditResponse: example: - objectStorageId: objectStorageId - cancelDate: 2021-06-02T00:00:00.000+0000 - displayName: Object storage 1 + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe properties: + id: + description: The ID of the audit entry. + example: 12345 + format: int64 + type: integer + action: + description: Type of the action. + enum: + - CREATED + - UPDATED + - DELETED + example: CREATED + type: string + timestamp: + description: When the change took place. + example: 2021-03-30T11:35:06.177Z + format: date-time + type: string tenantId: - description: Your customer tenant id + description: Customer tenant id example: DE minLength: 1 type: string customerId: - description: Your customer number + description: Customer ID example: "54321" minLength: 1 type: string - objectStorageId: - description: Object Storage id + changedBy: + description: Id of user who performed the change + example: c4c800ff-e524-47dd-9543-71dfc8b91113 + minLength: 1 type: string - cancelDate: - description: Cancellation date for object storage. - example: 2021-06-02 - format: date + username: + description: Name of the user which led to the change. + example: John.Doe type: string - displayName: - description: Display name for object storage. - example: Object storage 1 - maxLength: 255 - minLength: 1 + requestId: + description: The requestId of the API call which led to the change. + example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 type: string + traceId: + description: The traceId of the API call which led to the change. + example: 78E9A428-94E9-4A2A-92F5-26038C6884F + type: string + instanceId: + description: The identifier of the instance + example: 12345 + format: int64 + minimum: 0 + type: integer + changes: + description: List of actual changes. + example: + prev: + name: test + new: + name: test1 + type: object required: - - cancelDate + - action + - changedBy - customerId - - displayName - - objectStorageId + - id + - instanceId + - requestId - tenantId + - timestamp + - traceId + - username type: object - CancelObjectStorageResponse: + ListInstancesAuditResponse: example: data: - - objectStorageId: objectStorageId - cancelDate: 2021-06-02T00:00:00.000+0000 - displayName: Object storage 1 + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - - objectStorageId: objectStorageId - cancelDate: 2021-06-02T00:00:00.000+0000 - displayName: Object storage 1 + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe _links: - self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + first: /v1/compute/instances/audits?page=2 + previous: /v1/compute/instances/audits?page=2 + next: /v1/compute/instances/audits?page=3 + last: /v1/compute/instances/audits?page=10 + self: /v1/compute/instances/audits + _pagination: "" properties: - _links: + _pagination: allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/CancelObjectStorageResponseData' + $ref: '#/components/schemas/InstancesAuditResponse' type: array + _links: + allOf: + - $ref: '#/components/schemas/Links' + example: + first: /v1/compute/instances/audits?page=2 + previous: /v1/compute/instances/audits?page=2 + next: /v1/compute/instances/audits?page=3 + last: /v1/compute/instances/audits?page=10 + self: /v1/compute/instances/audits required: - _links + - _pagination - data type: object - PatchObjectStorageRequest: + TagResponse: example: - displayName: Object storage 1 + tagId: 12345 + tagName: Web-Server properties: - displayName: - description: Display name helps to differentiate between object storages, - especially if they are in the same region. - example: Object storage 1 + tagId: + description: Tag's id + example: 12345 + type: number + tagName: + description: Tag's name + example: Web-Server maxLength: 255 minLength: 1 type: string required: - - displayName - type: object - CreateTicketRequest: - example: - note: Note - sender: your@mail.com - subject: Subject - properties: - subject: - description: The ticket subject - example: Subject - minLength: 1 - type: string - note: - description: The ticket note - example: Note - minLength: 1 - type: string - sender: - description: Customer email - example: your@mail.com - minLength: 1 - type: string - required: - - note - - sender - - subject + - tagId + - tagName type: object - CreateTicketResponseData: + ListImageResponseData: example: + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + lastModifiedDate: 2021-06-04T06:27:12Z + format: iso + errorMessage: Error downloading image from provided URL + description: Ubuntu Server 20.04.2 LTS + sizeMb: 1024 + creationDate: 2021-06-03T06:27:12Z + version: 20.04.2 + url: https://example.com/image.qcow2 + tags: + - tagId: 12345 + tagName: Web-Server + - tagId: 12345 + tagName: Web-Server + uploadedSizeMb: 1024 tenantId: DE - customerId: "54321" + customerId: "12345" + name: Custom Image Ubuntu + osType: Linux + status: Pending + standardImage: true properties: + imageId: + description: Image's id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + type: string tenantId: description: Your customer tenant id + enum: + - DE + - INT example: DE minLength: 1 type: string customerId: - description: Your customer number - example: "54321" + description: Customer ID + example: "12345" minLength: 1 type: string + name: + description: Image Name + example: Custom Image Ubuntu + type: string + description: + description: Image Description + example: Ubuntu Server 20.04.2 LTS + type: string + url: + description: URL from where the image has been downloaded / provided. + example: https://example.com/image.qcow2 + type: string + sizeMb: + description: Image Size in MB + example: 1024 + type: number + uploadedSizeMb: + description: Image Uploaded Size in MB + example: 1024 + type: number + osType: + description: Type of operating system (OS) + example: Linux + type: string + version: + description: Version number to distinguish the contents of an image. Could + be the version of the operating system for example. + example: 20.04.2 + type: string + format: + description: Image format + enum: + - iso + - qcow2 + example: iso + type: string + status: + description: Image status (e.g. if image is still downloading) + example: Pending + type: string + errorMessage: + description: Image download error message + example: Error downloading image from provided URL + type: string + standardImage: + description: Flag indicating that image is either a standard (true) or a + custom image (false) + example: true + type: boolean + creationDate: + description: The creation date time for the image + example: 2021-06-03T06:27:12Z + format: date-time + type: string + lastModifiedDate: + description: The last modified date time for the image + example: 2021-06-04T06:27:12Z + format: date-time + type: string + tags: + description: The tags assigned to the image + items: + $ref: '#/components/schemas/TagResponse' + type: array required: + - creationDate - customerId + - description + - errorMessage + - format + - imageId + - lastModifiedDate + - name + - osType + - sizeMb + - standardImage + - status + - tags - tenantId + - uploadedSizeMb + - url + - version type: object - CreateTicketResponse: + ListImageResponse: example: data: - - tenantId: DE - customerId: "54321" - - tenantId: DE - customerId: "54321" + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + lastModifiedDate: 2021-06-04T06:27:12Z + format: iso + errorMessage: Error downloading image from provided URL + description: Ubuntu Server 20.04.2 LTS + sizeMb: 1024 + creationDate: 2021-06-03T06:27:12Z + version: 20.04.2 + url: https://example.com/image.qcow2 + tags: + - tagId: 12345 + tagName: Web-Server + - tagId: 12345 + tagName: Web-Server + uploadedSizeMb: 1024 + tenantId: DE + customerId: "12345" + name: Custom Image Ubuntu + osType: Linux + status: Pending + standardImage: true + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + lastModifiedDate: 2021-06-04T06:27:12Z + format: iso + errorMessage: Error downloading image from provided URL + description: Ubuntu Server 20.04.2 LTS + sizeMb: 1024 + creationDate: 2021-06-03T06:27:12Z + version: 20.04.2 + url: https://example.com/image.qcow2 + tags: + - tagId: 12345 + tagName: Web-Server + - tagId: 12345 + tagName: Web-Server + uploadedSizeMb: 1024 + tenantId: DE + customerId: "12345" + name: Custom Image Ubuntu + osType: Linux + status: Pending + standardImage: true _links: - self: /v1/create-ticket + first: /v1/compute/images?page=1 + previous: /v1/compute/images?page=19 + self: /v1/compute/images?page=20 + next: /v1/compute/images?page=21 + last: /v1/compute/images?page=101 + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/CreateTicketResponseData' + $ref: '#/components/schemas/ListImageResponseData' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/create-ticket + first: /v1/compute/images?page=1 + previous: /v1/compute/images?page=19 + self: /v1/compute/images?page=20 + next: /v1/compute/images?page=21 + last: /v1/compute/images?page=101 required: - _links + - _pagination - data type: object - ObjectStorageAuditResponse: + CreateCustomImageRequest: example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - objectStorageId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + name: Ubuntu Custom Image + osType: Linux + description: Ubuntu Server 20.04.2 LTS + version: 20.04.2 + url: https://example.com/image.qcow2 properties: - id: - description: The identifier of the audit entry. - example: 12345 - format: int64 - type: integer - action: - description: Type of the action. - enum: - - CREATED - - UPDATED - - DELETED - example: CREATED - type: string - timestamp: - description: When the change took place. - example: 2021-03-30T11:35:06.177Z - format: date-time - type: string - tenantId: - description: Customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Customer number - example: "54321" - minLength: 1 - type: string - changedBy: - description: User ID - example: "54321" - minLength: 1 + name: + description: Image Name + example: Ubuntu Custom Image type: string - username: - description: Name of the user which led to the change. - example: John.Doe + description: + description: Image Description + example: Ubuntu Server 20.04.2 LTS type: string - requestId: - description: The requestId of the API call which led to the change. - example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + url: + description: URL from where the image has been downloaded / provided. + example: https://example.com/image.qcow2 type: string - traceId: - description: The traceId of the API call which led to the change. - example: 78E9A428-94E9-4A2A-92F5-26038C6884F + osType: + description: Provided type of operating system (OS). Please specify `Windows` + for MS Windows and `Linux` for other OS. Specifying wrong OS type may + lead to disfunctional cloud instance. + enum: + - Windows + - Linux + example: Linux type: string - objectStorageId: - description: Object Storage Id - example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + version: + description: Version number to distinguish the contents of an image. Could + be the version of the operating system for example. + example: 20.04.2 type: string - changes: - description: List of actual changes. - example: - prev: - name: test - new: - name: test1 - type: object - required: - - action - - changedBy - - customerId - - id - - objectStorageId - - requestId - - tenantId - - timestamp - - traceId - - username - type: object - ListObjectStorageAuditResponse: - example: - data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - objectStorageId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - objectStorageId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe - _links: - first: /v1/object-storages/audits?page=2 - previous: /v1/object-storages/audits?page=2 - next: /v1/object-storages/audits?page=3 - last: /v1/object-storages/audits?page=10 - self: /v1/object-storages/audits - _pagination: "" - properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. - data: - items: - $ref: '#/components/schemas/ObjectStorageAuditResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' - example: - first: /v1/object-storages/audits?page=2 - previous: /v1/object-storages/audits?page=2 - next: /v1/object-storages/audits?page=3 - last: /v1/object-storages/audits?page=10 - self: /v1/object-storages/audits required: - - _links - - _pagination - - data + - name + - osType + - url + - version type: object - TagResponse: + CreateCustomImageResponseData: example: - color: '#0A78C3' - tagId: 12345 + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d tenantId: DE customerId: "54321" - name: Web-Server properties: tenantId: description: Your customer tenant id @@ -9881,218 +9366,291 @@ components: example: "54321" minLength: 1 type: string - tagId: - description: Tag's id - example: 12345 - type: number - name: - description: Tag's name - example: Web-Server - maxLength: 255 - minLength: 1 - type: string - color: - description: Tag's color - example: '#0A78C3' - maxLength: 7 - minLength: 4 + imageId: + description: Image's id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d type: string required: - - color - customerId - - name - - tagId + - imageId - tenantId type: object - ListTagResponse: + CreateCustomImageResponse: example: data: - - color: '#0A78C3' - tagId: 12345 + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d tenantId: DE customerId: "54321" - name: Web-Server - - color: '#0A78C3' - tagId: 12345 + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d tenantId: DE customerId: "54321" - name: Web-Server _links: - first: /v1/tags?page=1 - previous: /v1/tags?page=19 - self: /v1/tags/12345 - next: /v1/tags?page=21 - last: /v1/tags?page=101 - _pagination: "" + self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/TagResponse' + $ref: '#/components/schemas/CreateCustomImageResponseData' type: array _links: allOf: - - $ref: '#/components/schemas/Links' + - $ref: '#/components/schemas/SelfLinks' example: - first: /v1/tags?page=1 - previous: /v1/tags?page=19 - self: /v1/tags/12345 - next: /v1/tags?page=21 - last: /v1/tags?page=101 + self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d required: - _links - - _pagination - data type: object - CreateTagRequest: - example: - color: '#0A78C3' - name: Web-Server + CreateCustomImageFailResponse: properties: - name: - description: The name of the tag. Tags may contain letters, numbers, colons, - dashes, and underscores. There is a limit of 255 characters per tag. - example: Web-Server - maxLength: 255 - minLength: 1 - type: string - color: - default: '#0A78C3' - description: 'The color of the tag. Color can be specified using hexadecimal - value. Default color is #0A78C3' - example: '#0A78C3' - maxLength: 7 - minLength: 4 + message: + description: 'Unsupported Media Type: Please provide a direct link to an + .iso or .qcow2 image.' + example: Unsupported Media Type type: string + statusCode: + description: statuscode:415 + example: 415 + type: integer required: - - color - - name + - message + - statusCode type: object - CreateTagResponseData: + ImageResponse: example: - tagId: 12345 + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + lastModifiedDate: 2021-06-04T06:27:12Z + format: iso + errorMessage: Error downloading image from provided URL + description: Ubuntu Server 20.04.2 LTS + sizeMb: 1024 + creationDate: 2021-06-03T06:27:12Z + version: 20.04.2 + url: https://example.com/image.qcow2 + uploadedSizeMb: 1024 tenantId: DE - customerId: "54321" + customerId: "12345" + name: Custom Image Ubuntu + osType: Linux + status: Pending + standardImage: true properties: - tenantId: + imageId: + description: Image's id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + type: string + tenantId: description: Your customer tenant id + enum: + - DE + - INT example: DE minLength: 1 type: string customerId: - description: Your customer number - example: "54321" + description: Customer ID + example: "12345" minLength: 1 type: string - tagId: - description: Tag's id - example: 12345 + name: + description: Image Name + example: Custom Image Ubuntu + type: string + description: + description: Image Description + example: Ubuntu Server 20.04.2 LTS + type: string + url: + description: URL from where the image has been downloaded / provided. + example: https://example.com/image.qcow2 + type: string + sizeMb: + description: Image Size in MB + example: 1024 + type: number + uploadedSizeMb: + description: Image Uploaded Size in MB + example: 1024 type: number + osType: + description: Type of operating system (OS) + example: Linux + type: string + version: + description: Version number to distinguish the contents of an image. Could + be the version of the operating system for example. + example: 20.04.2 + type: string + format: + description: Image format + enum: + - iso + - qcow2 + example: iso + type: string + status: + description: Image status (e.g. if image is still downloading) + example: Pending + type: string + errorMessage: + description: Image download error message + example: Error downloading image from provided URL + type: string + standardImage: + description: Flag indicating that image is either a standard (true) or a + custom image (false) + example: true + type: boolean + creationDate: + description: The creation date time for the image + example: 2021-06-03T06:27:12Z + format: date-time + type: string + lastModifiedDate: + description: The last modified date time for the image + example: 2021-06-04T06:27:12Z + format: date-time + type: string required: + - creationDate - customerId - - tagId + - description + - errorMessage + - format + - imageId + - lastModifiedDate + - name + - osType + - sizeMb + - standardImage + - status - tenantId + - uploadedSizeMb + - url + - version type: object - CreateTagResponse: + FindImageResponse: example: data: - - tagId: 12345 + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + lastModifiedDate: 2021-06-04T06:27:12Z + format: iso + errorMessage: Error downloading image from provided URL + description: Ubuntu Server 20.04.2 LTS + sizeMb: 1024 + creationDate: 2021-06-03T06:27:12Z + version: 20.04.2 + url: https://example.com/image.qcow2 + uploadedSizeMb: 1024 tenantId: DE - customerId: "54321" - - tagId: 12345 + customerId: "12345" + name: Custom Image Ubuntu + osType: Linux + status: Pending + standardImage: true + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + lastModifiedDate: 2021-06-04T06:27:12Z + format: iso + errorMessage: Error downloading image from provided URL + description: Ubuntu Server 20.04.2 LTS + sizeMb: 1024 + creationDate: 2021-06-03T06:27:12Z + version: 20.04.2 + url: https://example.com/image.qcow2 + uploadedSizeMb: 1024 tenantId: DE - customerId: "54321" + customerId: "12345" + name: Custom Image Ubuntu + osType: Linux + status: Pending + standardImage: true _links: - self: /v1/tags/12345 + self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d properties: data: items: - $ref: '#/components/schemas/CreateTagResponseData' + $ref: '#/components/schemas/ImageResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/tags/12345 + self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d required: - _links - data type: object - FindTagResponse: + UpdateCustomImageRequest: example: - data: - - color: '#0A78C3' - tagId: 12345 - tenantId: DE - customerId: "54321" - name: Web-Server - - color: '#0A78C3' - tagId: 12345 - tenantId: DE - customerId: "54321" - name: Web-Server - _links: - self: /v1/tags/12345 + name: Ubuntu Custom Image + description: Ubuntu 20.04 image properties: - data: - items: - $ref: '#/components/schemas/TagResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/tags/12345 - required: - - _links - - data + name: + description: Image Name + example: Ubuntu Custom Image + type: string + description: + description: Image Description + example: Ubuntu 20.04 image + type: string type: object - UpdateTagRequest: + UpdateCustomImageResponseData: example: - color: '#0A78C3' - name: Updated-Web-Server + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + tenantId: DE + customerId: "54321" properties: - name: - description: The name of the tag. Tags may contain letters, numbers, colons, - dashes, and underscores. There is a limit of 255 characters per tag. - example: Updated-Web-Server - maxLength: 255 + tenantId: + description: Your customer tenant id + example: DE minLength: 1 type: string - color: - description: 'The color of the tag. Color can be specified using hexadecimal - value. Default color is #0A78C3' - example: '#0A78C3' - maxLength: 7 - minLength: 4 + customerId: + description: Your customer number + example: "54321" + minLength: 1 type: string + imageId: + description: Image's id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + type: string + required: + - customerId + - imageId + - tenantId type: object - UpdateTagResponse: + UpdateCustomImageResponse: example: + data: + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + tenantId: DE + customerId: "54321" + - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + tenantId: DE + customerId: "54321" _links: - self: /v1/tags/12345 + self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d properties: + data: + items: + $ref: '#/components/schemas/UpdateCustomImageResponseData' + type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' - description: Links for easy navigation. example: - self: /v1/tags/12345 + self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d required: - _links + - data type: object - AssignmentResponse: + CustomImagesStatsResponseData: example: - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - tagId: 12345 + currentImagesCount: 4 + usedSizeMb: 55000 tenantId: DE customerId: "54321" - resourceName: Instance - tagName: Web-Server - resourceType: instance + freeSizeMb: 47400 + totalSizeMb: 102400 properties: tenantId: description: Your customer tenant id @@ -10104,63 +9662,164 @@ components: example: "54321" minLength: 1 type: string - tagId: - description: Tag's id - example: 12345 + currentImagesCount: + description: The number of existing custom images + example: 4 + type: number + totalSizeMb: + description: Total available disk space in MB + example: 102400 + type: number + usedSizeMb: + description: Used disk space in MB + example: 55000 + type: number + freeSizeMb: + description: Free disk space in MB + example: 47400 type: number - tagName: - description: Tag's name - example: Web-Server - maxLength: 255 - minLength: 1 - type: string - resourceType: - description: Resource type. Resource type is one of `instance|image|object-storage`. - example: instance - minLength: 1 - type: string - resourceId: - description: Resource id - example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - minLength: 1 - type: string - resourceName: - description: Resource name - example: Instance - minLength: 1 - type: string required: + - currentImagesCount - customerId - - resourceId - - resourceName - - resourceType - - tagId - - tagName + - freeSizeMb - tenantId + - totalSizeMb + - usedSizeMb type: object - ListAssignmentResponse: + CustomImagesStatsResponse: example: data: - - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - tagId: 12345 + - currentImagesCount: 4 + usedSizeMb: 55000 tenantId: DE customerId: "54321" - resourceName: Instance - tagName: Web-Server - resourceType: instance - - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - tagId: 12345 + freeSizeMb: 47400 + totalSizeMb: 102400 + - currentImagesCount: 4 + usedSizeMb: 55000 tenantId: DE customerId: "54321" - resourceName: Instance - tagName: Web-Server - resourceType: instance + freeSizeMb: 47400 + totalSizeMb: 102400 _links: - first: /v1/tags/12345/assignments?page=1 - previous: /v1/tags/12345/assignments?page=19 - self: /v1/tags/12345/assignments/instance/23456 - next: /v1/tags/12345/assignments?page=21 - last: /v1/tags/12345/assignments?page=101 + self: /v1/compute/images/stats + properties: + data: + items: + $ref: '#/components/schemas/CustomImagesStatsResponseData' + type: array + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + example: + self: /v1/compute/images/stats + required: + - _links + - data + type: object + SnapshotResponse: + example: + snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 + tenantId: DE + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description + properties: + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + minLength: 1 + type: string + snapshotId: + description: Snapshot's id + example: snap1628603855 + type: string + name: + description: The name of the snapshot. + example: Snapshot-Server + maxLength: 255 + minLength: 1 + type: string + description: + description: The description of the snapshot. + example: Snapshot-Description + maxLength: 255 + minLength: 1 + type: string + instanceId: + description: The instance identifier associated with the snapshot + example: 1234 + format: int64 + type: integer + createdDate: + description: The date when the snapshot was created + example: 2021-06-02T12:32:03.363Z + format: date-time + type: string + autoDeleteDate: + description: The date when the snapshot will be auto-deleted + example: 2021-07-02T12:32:03.363Z + format: date-time + type: string + imageId: + description: Image Id the snapshot was taken on + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + type: string + imageName: + description: Image name the snapshot was taken on + example: ubuntu-18.04 + type: string + required: + - autoDeleteDate + - createdDate + - customerId + - description + - imageId + - imageName + - instanceId + - name + - snapshotId + - tenantId + type: object + ListSnapshotResponse: + example: + data: + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 + tenantId: DE + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 + tenantId: DE + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description + _links: + first: /v1/compute/instances/12345/snapshots?page=1 + next: /v1/compute/instances/12345/snapshots?page=19 + self: /v1/compute/instances/12345/snapshots/snap1628603855 + previous: /v1/compute/instances/12345/snapshots?page=21 + last: /v1/compute/instances/12345/snapshots?page=101 _pagination: "" properties: _pagination: @@ -10169,367 +9828,320 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/AssignmentResponse' + $ref: '#/components/schemas/SnapshotResponse' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/tags/12345/assignments?page=1 - previous: /v1/tags/12345/assignments?page=19 - self: /v1/tags/12345/assignments/instance/23456 - next: /v1/tags/12345/assignments?page=21 - last: /v1/tags/12345/assignments?page=101 + first: /v1/compute/instances/12345/snapshots?page=1 + next: /v1/compute/instances/12345/snapshots?page=19 + self: /v1/compute/instances/12345/snapshots/snap1628603855 + previous: /v1/compute/instances/12345/snapshots?page=21 + last: /v1/compute/instances/12345/snapshots?page=101 required: - _links - _pagination - data type: object - TagAssignmentSelfLinks: + CreateSnapshotRequest: + example: + name: Snapshot-Server + description: Snapshot-Description properties: - self: - description: Link to current resource. - type: string - tag: - description: Link to related tag. + name: + description: The name of the snapshot. It may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + snapshot. + example: Snapshot-Server + maxLength: 255 + minLength: 1 type: string - _resource: - description: Link to assigned resource + description: + description: The description of the snapshot. There is a limit of 255 characters + per snapshot. + example: Snapshot-Description + maxLength: 255 + minLength: 1 type: string required: - - _resource - - self - - tag + - name type: object - FindAssignmentResponse: + CreateSnapshotResponse: example: data: - - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - tagId: 12345 + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 tenantId: DE - customerId: "54321" - resourceName: Instance - tagName: Web-Server - resourceType: instance - - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc - tagId: 12345 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 tenantId: DE - customerId: "54321" - resourceName: Instance - tagName: Web-Server - resourceType: instance + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description _links: - self: /v1/tags/12345/assignments/instance/23456 - tag: /v1/tags/12345 - instance: /v1/compute/instances/23456 + self: /v1/compute/instances/12345/snapshots/snap1628603855 properties: data: items: - $ref: '#/components/schemas/AssignmentResponse' + $ref: '#/components/schemas/SnapshotResponse' type: array _links: allOf: - - $ref: '#/components/schemas/TagAssignmentSelfLinks' + - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/tags/12345/assignments/instance/23456 - tag: /v1/tags/12345 - instance: /v1/compute/instances/23456 + self: /v1/compute/instances/12345/snapshots/snap1628603855 required: - _links - data type: object - CreateAssignmentResponse: + FindSnapshotResponse: example: - _links: - self: /v1/tags/12345/assignments/instance/6549 - tag: /v1/tags/12345 - instance: /v1/compute/instance/6549 + data: + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 + tenantId: DE + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 + tenantId: DE + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description + _links: + self: /v1/compute/instances/12345/snapshots/snap1628603855 properties: + data: + items: + $ref: '#/components/schemas/SnapshotResponse' + type: array _links: allOf: - - $ref: '#/components/schemas/TagAssignmentSelfLinks' - description: Links for easy navigation. + - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/tags/12345/assignments/instance/6549 - tag: /v1/tags/12345 - instance: /v1/compute/instance/6549 + self: /v1/compute/instances/12345/snapshots/snap1628603855 required: - _links + - data type: object - TagAuditResponse: + UpdateSnapshotRequest: example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - tagId: 12345 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe + name: Snapshot-Server + description: Snapshot-Description properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: "54321" + name: + description: The name of the snapshot. Tags may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + snapshot. + example: Snapshot-Server + maxLength: 255 minLength: 1 type: string - id: - description: The identifier of the audit entry. - example: 12345 - type: number - tagId: - description: The identifier of the audit entry. - example: 12345 - minimum: 0 - type: number - action: - description: Type of the action. - enum: - - CREATED - - DELETED - - UPDATED - example: CREATED - type: string - timestamp: - description: When the change took place. - example: 2021-03-30T11:35:06.177Z - format: date-time - type: string - changedBy: - description: User ID - example: "54321" + description: + description: The description of the snapshot. There is a limit of 255 characters + per snapshot. + example: Snapshot-Description + maxLength: 255 minLength: 1 type: string - username: - description: Name of the user which led to the change. - example: John Doe - type: string - requestId: - description: The requestId of the API call which led to the change. - example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - type: string - traceId: - description: The traceId of the API call which led to the change. - example: 78E9A428-94E9-4A2A-92F5-26038C6884F - type: string - changes: - description: List of actual changes. - example: - prev: - name: test - new: - name: test1 - type: object - required: - - action - - changedBy - - customerId - - id - - requestId - - tagId - - tenantId - - timestamp - - traceId - - username type: object - ListTagAuditsResponse: + UpdateSnapshotResponse: example: data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - tagId: 12345 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - tagId: 12345 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description + - snapshotId: snap1628603855 + instanceId: 1234 + createdDate: 2021-06-02T12:32:03.363Z + autoDeleteDate: 2021-07-02T12:32:03.363Z + imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + imageName: ubuntu-18.04 tenantId: DE - customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe + customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + name: Snapshot-Server + description: Snapshot-Description _links: - first: /v1/tags/audits?page=1 - previous: /v1/tags/audits?page=19 - self: /v1/tags/audits?page=20 - next: /v1/tags/audits?page=21 - last: /v1/tags/audits?page=101 - _pagination: "" + self: /v1/compute/instances/12345/snapshots/snap1628603855 properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/TagAuditResponse' + $ref: '#/components/schemas/SnapshotResponse' type: array _links: allOf: - - $ref: '#/components/schemas/Links' + - $ref: '#/components/schemas/SelfLinks' example: - first: /v1/tags/audits?page=1 - previous: /v1/tags/audits?page=19 - self: /v1/tags/audits?page=20 - next: /v1/tags/audits?page=21 - last: /v1/tags/audits?page=101 + self: /v1/compute/instances/12345/snapshots/snap1628603855 required: - _links - - _pagination - data type: object - AssignmentAuditResponse: + RollbackSnapshotRequest: + properties: {} + type: object + RollbackSnapshotResponse: example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F5 - resourceId: a1b2c3 - tagId: 12345 - changes: '{}' - changedBy: "54321" - requestId: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 - tenantId: DE - customerId: "54321" - action: CREATED | DELETED - id: 12345 - resourceType: instance - timestamp: 2000-01-23T04:56:07.000+00:00 - username: John Doe + _links: + self: /v1/compute/instances/12345/snapshots/snap1628603855 properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 - type: string - id: - description: The identifier of the audit entry. - example: 12345 - type: number - resourceId: - description: Resource's id - example: a1b2c3 + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + description: Links for easy navigation. + example: + self: /v1/compute/instances/12345/snapshots/snap1628603855 + required: + - _links + type: object + ApplicationConfig: + properties: + imageId: + description: Image ID + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d type: string - resourceType: - description: Resource type. Resource type is one of `instance|image|object-storage`. - example: instance + userDataId: + description: User Data ID + example: 8b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d type: string - tagId: - description: Tag's id - example: 12345 - minimum: 0 + userData: + description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize + during start of compute instance.' + example: |- + #cloud-config + user: admin + timezone: Europe/Berlin + chpasswd: + expire: False + type: string + required: + - imageId + - userData + - userDataId + type: object + MinimumRequirements: + properties: + cpuCores: + description: CPU Cores Requirement + example: 2 type: number - action: - description: Audit Action - enum: - - CREATED - - DELETED - example: CREATED | DELETED + ramMb: + description: Memory Requirement in MB + example: 100 + type: number + diskMb: + description: Storage Requirement in MB + example: 500 + type: number + type: object + OptimalRequirements: + properties: + cpuCores: + description: CPU Cores Requirement + example: 2 + type: number + ramMb: + description: Memory Requirement in MB + example: 100 + type: number + diskMb: + description: Storage Requirement in MB + example: 500 + type: number + type: object + ApplicationRequirements: + properties: + minimum: + allOf: + - $ref: '#/components/schemas/MinimumRequirements' + description: Application minimum requirements + optimal: + allOf: + - $ref: '#/components/schemas/OptimalRequirements' + description: Application optimal requirements + type: object + ApplicationResponse: + properties: + applicationId: + description: Application ID + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d type: string - timestamp: - description: Audit creation date - format: date-time + tenantId: + description: Tenant ID + enum: + - DE + - INT + example: DE + minLength: 1 type: string - changedBy: - description: User ID - example: "54321" + customerId: + description: Customer ID + example: "12345" minLength: 1 type: string - username: - description: User Full Name - example: John Doe + name: + description: Application Name + example: Webmin type: string - requestId: - description: Request ID - example: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 + description: + description: Application Description + example: Webmin cloud init type: string - traceId: - description: Trace ID - example: 78E9A428-94E9-4A2A-92F5-26038C6884F5 + type: + description: Application type + enum: + - standard + - crypto + example: standard type: string - changes: - description: Changes made for a specific Tag - type: object + applicationConfig: + description: Application Config + items: + $ref: '#/components/schemas/ApplicationConfig' + type: array + requirements: + allOf: + - $ref: '#/components/schemas/ApplicationRequirements' + description: Application Requirements required: - - action - - changedBy + - applicationConfig + - applicationId - customerId - - id - - requestId - - resourceId - - resourceType - - tagId + - description + - name + - requirements - tenantId - - timestamp - - traceId - - username + - type type: object - ListAssignmentAuditsResponse: - example: - data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F5 - resourceId: a1b2c3 - tagId: 12345 - changes: '{}' - changedBy: "54321" - requestId: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 - tenantId: DE - customerId: "54321" - action: CREATED | DELETED - id: 12345 - resourceType: instance - timestamp: 2000-01-23T04:56:07.000+00:00 - username: John Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F5 - resourceId: a1b2c3 - tagId: 12345 - changes: '{}' - changedBy: "54321" - requestId: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 - tenantId: DE - customerId: "54321" - action: CREATED | DELETED - id: 12345 - resourceType: instance - timestamp: 2000-01-23T04:56:07.000+00:00 - username: John Doe - _links: - first: /v1/tags/assignments/audits?page=1 - previous: /v1/tags/assignments/audits?page=19 - self: /v1/tags/assignments/audits?page=20 - next: /v1/tags/assignments/audits?page=21 - last: /v1/tags/assignments/audits?page=101 - _pagination: "" + ListApplicationsResponse: properties: _pagination: allOf: @@ -10537,428 +10149,212 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/AssignmentAuditResponse' + $ref: '#/components/schemas/ApplicationResponse' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/tags/assignments/audits?page=1 - previous: /v1/tags/assignments/audits?page=19 - self: /v1/tags/assignments/audits?page=20 - next: /v1/tags/assignments/audits?page=21 - last: /v1/tags/assignments/audits?page=101 + first: /v1/compute/applications?page=1 + previous: /v1/compute/applications?page=19 + self: /v1/compute/applications?page=20 + next: /v1/compute/applications?page=21 + last: /v1/compute/applications?page=101 required: - _links - _pagination - data type: object - IpV4: - example: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 + VncResponse: properties: - ip: - description: IP Address - example: 192.168.0.1 + tenantId: + description: Your customer tenant id + enum: + - DE + - INT + example: DE + minLength: 1 type: string - netmaskCidr: - description: Netmask CIDR - example: 19 - format: int32 + customerId: + description: Customer ID + example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + minLength: 1 + type: string + instanceId: + description: Instance ID + example: 100 + format: int64 type: integer - gateway: - description: Gateway - example: 1.1.1.1 + enabled: + description: VNC Status for the instance. + example: true + type: boolean + vncIp: + description: VNC IP for the instance. + example: 154.12.54.123 type: string + vncPort: + description: VNC Port for the instance. + example: 8001 + type: number required: - - gateway - - ip - - netmaskCidr + - customerId + - enabled + - instanceId + - tenantId + - vncIp + - vncPort type: object - PrivateIpConfig: - example: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 + FindVncResponse: properties: - v4: + data: items: - $ref: '#/components/schemas/IpV4' + $ref: '#/components/schemas/VncResponse' type: array + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + example: + self: /v1/compute/instances/100/vnc required: - - v4 + - _links + - data type: object - IpV6: - example: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 + PatchVncRequest: properties: - ip: - description: IP Address - example: 1:2:3:4:5:6:7:8 - type: string - netmaskCidr: - description: Netmask CIDR - example: 64 - format: int32 - type: integer - gateway: - description: Gateway - example: 1:2:3:4:5:6:7:8 + vncPassword: + description: Password for instance VNC + example: test123 type: string required: - - gateway - - ip - - netmaskCidr - type: object - IpConfig: - example: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - properties: - v4: - $ref: '#/components/schemas/IpV4' - v6: - $ref: '#/components/schemas/IpV6' - required: - - v4 - - v6 + - vncPassword type: object - Instances: + ImageAuditResponseData: example: - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + imageId: e443eab5-647a-4bc3-b4f9-16f5a281224d + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + tenantId: DE + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe properties: - instanceId: - description: Instance id - example: 100 + id: + description: The ID of the audit entry. + example: 12345 format: int64 type: integer - displayName: - description: Instance display name - example: Instance - type: string - name: - description: Instance name - example: vmd12345 - type: string - productId: - description: Product id - example: V1 - type: string - privateIpConfig: - $ref: '#/components/schemas/PrivateIpConfig' - ipConfig: - $ref: '#/components/schemas/IpConfig' - status: - description: State of the instance in the Private Network + action: + description: Type of the action. enum: - - ok - - restart - - reinstall - - reinstallation failed - - installing - example: ok + - CREATED + - UPDATED + - DELETED + example: CREATED type: string - errorMessage: - description: Message in case of an error. + timestamp: + description: When the change took place. + example: 2021-03-30T11:35:06.177Z + format: date-time type: string - required: - - displayName - - instanceId - - ipConfig - - name - - privateIpConfig - - productId - - status - type: object - ListPrivateNetworkResponseData: - example: - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) - tenantId: DE - customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU - properties: tenantId: - description: Your customer tenant id + description: Customer tenant id example: DE minLength: 1 type: string customerId: - description: Your customer number + description: Customer ID example: "54321" minLength: 1 type: string - privateNetworkId: - description: Private Network's id - example: 12345 - format: int64 - type: integer - dataCenter: - description: The data center where your Private Network is located - example: European Union (Germany) 1 - type: string - region: - description: The slug of the region where your Private Network is located - example: EU - type: string - regionName: - description: The region where your Private Network is located - example: European Union (Germany) + changedBy: + description: Id of user who performed the change + example: c4c800ff-e524-47dd-9543-71dfc8b91113 + minLength: 1 type: string - name: - description: The name of the Private Network - example: myPrivateNetwork + username: + description: Name of the user which led to the change. + example: John.Doe type: string - description: - description: The description of the Private Network - example: myPrivateNetwork Description + requestId: + description: The requestId of the API call which led to the change. + example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 type: string - cidr: - description: The cidr range of the Private Network - example: 10.0.0.0/22 + traceId: + description: The traceId of the API call which led to the change. + example: 78E9A428-94E9-4A2A-92F5-26038C6884F type: string - availableIps: - description: The total available IPs of the Private Network - example: 1022 - format: int64 - type: integer - createdDate: - description: The creation date of the Private Network - example: 2021-06-03T06:27:12Z - format: date-time + imageId: + description: The identifier of the image + example: e443eab5-647a-4bc3-b4f9-16f5a281224d type: string - instances: - items: - $ref: '#/components/schemas/Instances' - type: array + changes: + description: List of actual changes. + example: + prev: + name: test + new: + name: test1 + type: object required: - - availableIps - - cidr - - createdDate + - action + - changedBy - customerId - - dataCenter - - description - - instances - - name - - privateNetworkId - - region - - regionName + - id + - imageId + - requestId - tenantId + - timestamp + - traceId + - username type: object - ListPrivateNetworkResponse: + ImageAuditResponse: example: data: - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + imageId: e443eab5-647a-4bc3-b4f9-16f5a281224d + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + imageId: e443eab5-647a-4bc3-b4f9-16f5a281224d + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe _links: - first: /v1/private-networks?page=1 - previous: /v1/private-networks?page=19 - self: /v1/private-networks?page=20 - next: /v1/private-networks?page=21 - last: /v1/private-networks?page=101 + first: /v1/compute/images/audits?page=2 + previous: /v1/compute/images/audits?page=2 + next: /v1/compute/images/audits?page=3 + last: /v1/compute/images/audits?page=10 + self: /v1/compute/images/audits _pagination: "" properties: _pagination: @@ -10967,112 +10363,219 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/ListPrivateNetworkResponseData' + $ref: '#/components/schemas/ImageAuditResponseData' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/private-networks?page=1 - previous: /v1/private-networks?page=19 - self: /v1/private-networks?page=20 - next: /v1/private-networks?page=21 - last: /v1/private-networks?page=101 + first: /v1/compute/images/audits?page=2 + previous: /v1/compute/images/audits?page=2 + next: /v1/compute/images/audits?page=3 + last: /v1/compute/images/audits?page=10 + self: /v1/compute/images/audits required: - _links - _pagination - data type: object - CreatePrivateNetworkRequest: + SnapshotsAuditResponse: example: - name: myPrivateNetwork - description: myPrivateNetwork Description - region: EU + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + snapshotId: snap1628603855 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + tenantId: DE + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe properties: - region: - default: EU - description: Region where the Private Network should be located. Default - is `EU` - example: EU + id: + description: The ID of the audit entry. + example: 12345 + format: int64 + type: integer + action: + description: Type of the action. + enum: + - CREATED + - UPDATED + - DELETED + example: CREATED + type: string + timestamp: + description: When the change took place. + example: 2021-03-30T11:35:06.177Z + format: date-time + type: string + tenantId: + description: Customer tenant id + example: DE minLength: 1 type: string - name: - description: The name of the Private Network. It may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - Private Network name. - example: myPrivateNetwork - maxLength: 255 + customerId: + description: Customer ID + example: "54321" minLength: 1 type: string - description: - description: The description of the Private Network. There is a limit of - 255 characters per Private Network description. - example: myPrivateNetwork Description - maxLength: 255 + changedBy: + description: Id of user who performed the change + example: c4c800ff-e524-47dd-9543-71dfc8b91113 + minLength: 1 type: string - required: - - name - type: object - PrivateNetworkResponse: + username: + description: Name of the user which led to the change. + example: John.Doe + type: string + requestId: + description: The requestId of the API call which led to the change. + example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + type: string + traceId: + description: The traceId of the API call which led to the change. + example: 78E9A428-94E9-4A2A-92F5-26038C6884F + type: string + instanceId: + description: The identifier of the instance + example: 12345 + format: int64 + minimum: 0 + type: integer + snapshotId: + description: The identifier of the snapshot + example: snap1628603855 + type: string + changes: + description: List of actual changes + example: + prev: + name: test + new: + name: test1 + type: object + required: + - action + - changedBy + - customerId + - id + - instanceId + - requestId + - snapshotId + - tenantId + - timestamp + - traceId + - username + type: object + ListSnapshotsAuditResponse: example: - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) + data: + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + snapshotId: snap1628603855 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + tenantId: DE + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + instanceId: 12345 + snapshotId: snap1628603855 + changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + tenantId: DE + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe + _links: + first: /v1/compute/snapshots/audits?page=2 + previous: /v1/compute/snapshots/audits?page=2 + next: /v1/compute/snapshots/audits?page=3 + last: /v1/compute/snapshots/audits?page=10 + self: /v1/compute/snapshots/audits + _pagination: "" + properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. + data: + items: + $ref: '#/components/schemas/SnapshotsAuditResponse' + type: array + _links: + allOf: + - $ref: '#/components/schemas/Links' + example: + first: /v1/compute/snapshots/audits?page=2 + previous: /v1/compute/snapshots/audits?page=2 + next: /v1/compute/snapshots/audits?page=3 + last: /v1/compute/snapshots/audits?page=10 + self: /v1/compute/snapshots/audits + required: + - _links + - _pagination + - data + type: object + AutoScalingTypeResponse: + properties: + state: + description: State of the autoscaling for the current object storage. + enum: + - enabled + - disabled + - error + example: enabled + type: string + sizeLimitTB: + description: Autoscaling size limit for the current object storage. + example: 1 + format: double + type: number + errorMessage: + description: Error message + type: string + required: + - sizeLimitTB + - state + type: object + ObjectStorageResponse: + example: + objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU + region: European Union (Germany) + status: READY properties: tenantId: description: Your customer tenant id @@ -11084,747 +10587,715 @@ components: example: "54321" minLength: 1 type: string - privateNetworkId: - description: Private Network's id - example: 12345 - format: int64 - type: integer - dataCenter: - description: The data center where your Private Network is located - example: European Union (Germany) 1 + objectStorageId: + description: Your object storage id + example: b943b25a-c8b5-4570-9135-4bbaa7615b81 + minLength: 1 type: string - region: - description: The slug of the region where your Private Network is located - example: EU + createdDate: + description: Creation date for object storage. + example: 2021-06-02T12:32:03.363Z + format: date-time type: string - regionName: - description: The region where your Private Network is located - example: European Union (Germany) + cancelDate: + description: Cancellation date for object storage. + example: 2021-06-02 + format: date type: string - name: - description: The name of the Private Network - example: myPrivateNetwork + autoScaling: + allOf: + - $ref: '#/components/schemas/AutoScalingTypeResponse' + description: Autoscaling settings + dataCenter: + description: Data center your object storage is located + example: EU + minLength: 1 type: string - description: - description: The description of the Private Network - example: myPrivateNetwork Description + totalPurchasedSpaceTB: + description: Amount of purchased / requested object storage in TB. + example: 6.25 + format: double + type: number + s3Url: + description: S3 URL to connect to your S3 compatible object storage + example: eu1-s3.contabo.com type: string - cidr: - description: The cidr range of the Private Network - example: 10.0.0.0/22 + s3TenantId: + description: Your S3 tenantId. Only required for public sharing. + example: 2cd2e5e1444a41b0bed16c6410ecaa84 type: string - availableIps: - description: The total available IPs of the Private Network - example: 1022 - format: int64 - type: integer - createdDate: - description: The creation date of the Private Network - example: 2021-06-03T06:27:12Z - format: date-time + status: + description: The object storage status + enum: + - READY + - PROVISIONING + - UPGRADING + - CANCELLED + - ERROR + - ENABLED + - DISABLED + - MANUAL_PROVISIONING + - PRODUCT_NOT_AVAILABLE + - LIMIT_EXCEEDED + - VERIFICATION_REQUIRED + - COMPLETED + - ORDER_PROCESSING + - PENDING_PAYMENT + - UNKNOWN + example: READY + type: string + region: + description: The region where your object storage is located + example: European Union (Germany) + type: string + displayName: + description: Display name for object storage. + example: Object storage 1 + maxLength: 255 + minLength: 1 type: string - instances: - items: - $ref: '#/components/schemas/Instances' - type: array required: - - availableIps - - cidr + - autoScaling + - cancelDate - createdDate - customerId - dataCenter - - description - - instances - - name - - privateNetworkId + - displayName + - objectStorageId - region - - regionName + - s3TenantId + - s3Url + - status - tenantId + - totalPurchasedSpaceTB type: object - CreatePrivateNetworkResponse: + ListObjectStorageResponse: example: data: - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) + - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) + region: European Union (Germany) + status: READY + - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU + region: European Union (Germany) + status: READY _links: - self: /v1/private-networks/12345 + first: /v1/object-storages?size=10 + previous: /v1/object-storages?page=1&size=10 + next: /v1/object-storages?page=3&size=10 + last: /v1/object-storages?page=5&size=10 + self: /v1/object-storages + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/PrivateNetworkResponse' + $ref: '#/components/schemas/ObjectStorageResponse' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/private-networks/12345 + first: /v1/object-storages?size=10 + previous: /v1/object-storages?page=1&size=10 + next: /v1/object-storages?page=3&size=10 + last: /v1/object-storages?page=5&size=10 + self: /v1/object-storages required: - _links + - _pagination - data type: object - PatchPrivateNetworkRequest: + DataCenterResponse: example: - name: myPrivateNetwork - description: myPrivateNetwork Description + s3Url: eu1-s3.contabo.com + capabilities: + - VPS + - Object-Storage + regionSlug: EU + regionName: European Union (Germany) + name: European Union (Germany) 1 + tenantId: DE + customerId: "54321" + slug: EU1 properties: name: - description: The name of the Private Network. It may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - Private Network. - example: myPrivateNetwork - maxLength: 255 + description: Name of the data center + example: European Union (Germany) 1 minLength: 1 type: string - description: - description: The description of the Private Network. There is a limit of - 255 characters per Private Network. - example: myPrivateNetwork Description - maxLength: 255 + slug: + description: Slug of the data center + example: EU1 + minLength: 1 type: string - type: object - PatchPrivateNetworkResponse: - example: - data: - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok + capabilities: + example: + - VPS + - Object-Storage + items: + enum: + - VPS + - VDS + - Object-Storage + - Private-Networking + type: string + type: array + s3Url: + description: S3 URL of the data center + example: eu1-s3.contabo.com + minLength: 1 + type: string + regionName: + description: Name of the region + example: European Union (Germany) + minLength: 1 + type: string + regionSlug: + description: Slug of the region + example: EU + minLength: 1 + type: string + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + required: + - capabilities + - customerId + - name + - regionName + - regionSlug + - s3Url + - slug + - tenantId + type: object + ListDataCenterResponse: + example: + data: + - s3Url: eu1-s3.contabo.com + capabilities: + - VPS + - Object-Storage + regionSlug: EU regionName: European Union (Germany) + name: European Union (Germany) 1 tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok + slug: EU1 + - s3Url: eu1-s3.contabo.com + capabilities: + - VPS + - Object-Storage + regionSlug: EU regionName: European Union (Germany) + name: European Union (Germany) 1 tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU + slug: EU1 _links: - self: /v1/private-networks/12345 + first: /v1/data-centers?page=1 + previous: /v1/data-centers?page=19 + self: /v1/data-centers/12345 + next: /v1/data-centers?page=21 + last: /v1/data-centers?page=101 + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/PrivateNetworkResponse' + $ref: '#/components/schemas/DataCenterResponse' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/private-networks/12345 + first: /v1/data-centers?page=1 + previous: /v1/data-centers?page=19 + self: /v1/data-centers/12345 + next: /v1/data-centers?page=21 + last: /v1/data-centers?page=101 required: - _links + - _pagination - data type: object - FindPrivateNetworkResponse: + AutoScalingTypeRequest: + properties: + state: + description: State of the autoscaling for the current object storage. + enum: + - enabled + - disabled + example: enabled + type: string + sizeLimitTB: + description: Autoscaling size limit for the current object storage. + example: 1 + format: double + type: number + required: + - sizeLimitTB + - state + type: object + CreateObjectStorageRequest: + example: + autoScaling: "" + displayName: Object storage 1 + region: EU + totalPurchasedSpaceTB: 6 + properties: + region: + default: EU + description: 'Region where the object storage should be located. Default + is EU. Available regions: EU, US-central, SIN' + example: EU + minLength: 1 + type: string + autoScaling: + allOf: + - $ref: '#/components/schemas/AutoScalingTypeRequest' + description: Autoscaling settings + totalPurchasedSpaceTB: + description: Amount of purchased / requested object storage in TB. + example: 6 + format: double + type: number + displayName: + description: Display name helps to differentiate between object storages, + especially if they are in the same region. If display name is not provided, + it will be generated. Display name can be changed any time. + example: Object storage 1 + maxLength: 255 + minLength: 1 + type: string + required: + - region + - totalPurchasedSpaceTB + type: object + CreateObjectStorageResponseData: + example: + objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + usedSpacePercentage: 100 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z + usedSpaceTB: 4 + tenantId: DE + customerId: "54321" + region: European Union (Germany) + status: READY + properties: + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + objectStorageId: + description: Your object storage id + example: b943b25a-c8b5-4570-9135-4bbaa7615b81 + minLength: 1 + type: string + createdDate: + description: Creation date for object storage. + example: 2021-06-02T12:32:03.363Z + format: date-time + type: string + cancelDate: + description: Cancellation date for object storage. + example: 2021-06-02 + format: date + type: string + autoScaling: + allOf: + - $ref: '#/components/schemas/AutoScalingTypeResponse' + description: Autoscaling settings + dataCenter: + description: The data center of the storage + example: EU + minLength: 1 + type: string + totalPurchasedSpaceTB: + description: Amount of purchased / requested object storage in TB. + example: 6.25 + format: double + type: number + usedSpaceTB: + description: Currently used space in TB. + example: 4 + format: double + type: number + usedSpacePercentage: + description: Currently used space in percentage. + example: 100 + format: double + maximum: 100 + minimum: 0 + type: number + s3Url: + description: S3 URL to connect to your S3 compatible object storage + example: eu1-s3.contabo.com + type: string + s3TenantId: + description: Your S3 tenantId. Only required for public sharing. + example: 2cd2e5e1444a41b0bed16c6410ecaa84 + type: string + status: + description: The object storage status + enum: + - READY + - PROVISIONING + - UPGRADING + - CANCELLED + - ERROR + - ENABLED + - DISABLED + - MANUAL_PROVISIONING + - PRODUCT_NOT_AVAILABLE + - LIMIT_EXCEEDED + - VERIFICATION_REQUIRED + - COMPLETED + - ORDER_PROCESSING + - PENDING_PAYMENT + - UNKNOWN + example: READY + minLength: 1 + type: string + region: + description: The region where your object storage is located + example: European Union (Germany) + type: string + displayName: + description: Display name for object storage. + example: Object storage 1 + maxLength: 255 + minLength: 1 + type: string + required: + - autoScaling + - cancelDate + - createdDate + - customerId + - dataCenter + - displayName + - objectStorageId + - region + - s3TenantId + - s3Url + - status + - tenantId + - totalPurchasedSpaceTB + - usedSpacePercentage + - usedSpaceTB + type: object + CreateObjectStorageResponse: example: data: - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) - tenantId: DE - customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU - - createdDate: 2021-06-03T06:27:12Z - privateNetworkId: 12345 - dataCenter: European Union (Germany) 1 - availableIps: 1022 - instances: - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - instanceId: 100 - productId: V1 - displayName: Instance - name: vmd12345 - errorMessage: errorMessage - privateIpConfig: - v4: - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - status: ok - regionName: European Union (Germany) + - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + usedSpacePercentage: 100 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z + usedSpaceTB: 4 tenantId: DE customerId: "54321" - name: myPrivateNetwork - description: myPrivateNetwork Description - cidr: 10.0.0.0/22 - region: EU + region: European Union (Germany) + status: READY + - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + usedSpacePercentage: 100 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z + usedSpaceTB: 4 + tenantId: DE + customerId: "54321" + region: European Union (Germany) + status: READY _links: - self: /v1/private-networks/12345 + self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 properties: data: items: - $ref: '#/components/schemas/PrivateNetworkResponse' + $ref: '#/components/schemas/CreateObjectStorageResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/private-networks/12345 + self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 required: - _links - data type: object - InstanceAssignmentSelfLinks: - properties: - self: - description: Link to current resource. - type: string - virtualPrivateCloud: - description: Link to related Private Network. - type: string - instance: - description: Link to assigned instance. - type: string - required: - - instance - - self - - virtualPrivateCloud - type: object - AssignInstancePrivateNetworkResponse: + FindObjectStorageResponse: example: + data: + - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z + tenantId: DE + customerId: "54321" + region: European Union (Germany) + status: READY + - objectStorageId: b943b25a-c8b5-4570-9135-4bbaa7615b81 + cancelDate: 2021-06-02T00:00:00.000+0000 + s3Url: eu1-s3.contabo.com + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 + totalPurchasedSpaceTB: 6.25 + s3TenantId: 2cd2e5e1444a41b0bed16c6410ecaa84 + createdDate: 2021-06-02T12:32:03.363Z + tenantId: DE + customerId: "54321" + region: European Union (Germany) + status: READY _links: - self: /v1/private-networks/12345/instances/100 - virtualPrivateCloud: /v1/private-networks/12345 - instance: /v1/compute/instances/100 + self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 properties: + data: + items: + $ref: '#/components/schemas/ObjectStorageResponse' + type: array _links: allOf: - - $ref: '#/components/schemas/InstanceAssignmentSelfLinks' - description: Links for easy navigation. + - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/private-networks/12345/instances/100 - virtualPrivateCloud: /v1/private-networks/12345 - instance: /v1/compute/instances/100 + self: /v1/object-storages/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 required: - _links + - data type: object - UnassignInstancePrivateNetworkResponse: + UpgradeAutoScalingType: + properties: + state: + description: State of the autoscaling for the current object storage. + enum: + - enabled + - disabled + example: enabled + type: string + sizeLimitTB: + description: Autoscaling size limit for the current object storage. + example: 6 + format: double + type: number + type: object + UpgradeObjectStorageRequest: example: - _links: - self: /v1/private-networks/12345/instances/100 - virtualPrivateCloud: /v1/private-networks/12345 - instance: /v1/compute/instances/100 + autoScaling: "" + totalPurchasedSpaceTB: 8 properties: - _links: + autoScaling: allOf: - - $ref: '#/components/schemas/InstanceAssignmentSelfLinks' - description: Links for easy navigation. - example: - self: /v1/private-networks/12345/instances/100 - virtualPrivateCloud: /v1/private-networks/12345 - instance: /v1/compute/instances/100 - required: - - _links + - $ref: '#/components/schemas/UpgradeAutoScalingType' + description: New monthly object storage size limit for autoscaling if enabled. + totalPurchasedSpaceTB: + description: New total object storage limit. If this number is larger than + before you will also be billed for the added storage space. No downgrade + possible. + example: 8 + format: double + type: number type: object - PrivateNetworkAuditResponse: + UpgradeObjectStorageResponseData: example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - privateNetworkId: 12345 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + objectStorageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + s3Url: eu1-s3.contabo.com + createdDate: 2021-06-02T12:32:03.363Z + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe + region: European Union (Germany) + totalPurchasedSpaceTB: 6 + status: READY properties: - id: - description: The identifier of the audit entry. - example: 12345 - format: int64 - type: integer - privateNetworkId: - description: The identifier of the Private Network - example: 12345 - minimum: 0 - type: number - action: - description: Type of the action. - enum: - - CREATED - - DELETED - - UPDATED - example: CREATED - type: string - timestamp: - description: When the change took place. - example: 2021-03-30T11:35:06.177Z - format: date-time - type: string tenantId: - description: Customer tenant id + description: Your customer tenant id example: DE minLength: 1 type: string customerId: - description: Customer number + description: Your customer number example: "54321" minLength: 1 type: string - changedBy: - description: User id - example: "54321" + objectStorageId: + description: Object storage id + example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d minLength: 1 type: string - username: - description: User name which did the change. - example: John Doe + createdDate: + description: Creation date for object storage. + example: 2021-06-02T12:32:03.363Z type: string - requestId: - description: The requestId of the API call which led to the change. - example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + dataCenter: + description: Data center of the object storage. + example: EU type: string - traceId: - description: The traceId of the API call which led to the change. - example: 78E9A428-94E9-4A2A-92F5-26038C6884F + autoScaling: + allOf: + - $ref: '#/components/schemas/AutoScalingTypeResponse' + description: The autoscaling limit of the object storage. + s3Url: + description: S3 URL to connect to your S3 compatible object storage + example: eu1-s3.contabo.com + type: string + status: + description: The object storage status + enum: + - READY + - PROVISIONING + - UPGRADING + - CANCELLED + - ERROR + - ENABLED + - DISABLED + - MANUAL_PROVISIONING + - PRODUCT_NOT_AVAILABLE + - LIMIT_EXCEEDED + - VERIFICATION_REQUIRED + - COMPLETED + - ORDER_PROCESSING + - PENDING_PAYMENT + - UNKNOWN + example: READY + type: string + totalPurchasedSpaceTB: + description: Total purchased object storage space in TB. + example: 6 + format: double + type: number + region: + description: The region where your object storage is located + example: European Union (Germany) + type: string + displayName: + description: Display name for object storage. + example: Object storage 1 + maxLength: 255 + minLength: 1 type: string - changes: - description: List of actual changes. - example: - prev: - name: test - new: - name: test1 - type: object required: - - action - - changedBy + - autoScaling + - createdDate - customerId - - id - - privateNetworkId - - requestId + - dataCenter + - displayName + - objectStorageId + - region + - s3Url + - status - tenantId - - timestamp - - traceId - - username + - totalPurchasedSpaceTB type: object - ListPrivateNetworkAuditResponse: + UpgradeObjectStorageResponse: example: data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - privateNetworkId: 12345 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + - objectStorageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + s3Url: eu1-s3.contabo.com + createdDate: 2021-06-02T12:32:03.363Z + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - privateNetworkId: 12345 - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + region: European Union (Germany) + totalPurchasedSpaceTB: 6 + status: READY + - objectStorageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + s3Url: eu1-s3.contabo.com + createdDate: 2021-06-02T12:32:03.363Z + autoScaling: "" + dataCenter: EU + displayName: Object storage 1 tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe + region: European Union (Germany) + totalPurchasedSpaceTB: 6 + status: READY _links: - first: /v1/private-networks/audits?page=2 - previous: /v1/private-networks/audits?page=2 - next: /v1/private-networks/audits?page=3 - last: /v1/private-networks/audits?page=10 - self: /v1/private-networks/audits - _pagination: "" + self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d properties: - _pagination: + _links: allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. + - $ref: '#/components/schemas/SelfLinks' + example: + self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d data: items: - $ref: '#/components/schemas/PrivateNetworkAuditResponse' + $ref: '#/components/schemas/UpgradeObjectStorageResponseData' type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' - example: - first: /v1/private-networks/audits?page=2 - previous: /v1/private-networks/audits?page=2 - next: /v1/private-networks/audits?page=3 - last: /v1/private-networks/audits?page=10 - self: /v1/private-networks/audits required: - _links - - _pagination - data type: object - TicketCreateRequest: - example: - assignedGroup: Support - sourceClient: Website - subject: New support ticket - description: Some details on the issue - type: Incident - tags: '["test","beta"]' - properties: - description: - description: Ticket description - example: Some details on the issue - type: string - subject: - description: Ticket subject - example: New support ticket - type: string - tags: - description: Ticket tags - example: '["test","beta"]' - items: - type: string - type: array - type: - description: Ticket type - example: Incident - type: string - assignedGroup: - description: Ticket Group - example: Support - type: string - sourceClient: - description: Ticket Source - example: Website - type: string - required: - - description - - sourceClient - - subject - - type - type: object - TicketResponse: + ObjectStoragesStatsResponseData: example: - subject: New support ticket - description: Some details on the issue - updatedDate: 2023-11-14T10:22:48Z - priority: low - type: Incident - tags: '["test","beta"]' - createdDate: 2023-11-13T11:22:48Z + usedSpaceTB: 4 + numberOfObjects: 2 + usedSpacePercentage: 100 tenantId: DE customerId: "54321" - isEscalated: false - email: test-customer@test.com - ticketId: 1234 - status: open properties: tenantId: description: Your customer tenant id @@ -11836,129 +11307,66 @@ components: example: "54321" minLength: 1 type: string - email: - description: Ticket email - example: test-customer@test.com - type: string - isEscalated: - description: Ticket escalated flag - example: false - type: boolean - priority: - description: Ticket priority - enum: - - low - - medium - - high - - urgent - example: low - type: string - status: - description: Ticket status - enum: - - open - - pending - - resolved - - closed - example: open - type: string - subject: - description: Ticket subject - example: New support ticket - type: string - description: - description: Ticket description - example: Some details on the issue - type: string - createdDate: - description: Created Date - example: 2023-11-13T11:22:48Z - type: string - updatedDate: - description: Created Date - example: 2023-11-14T10:22:48Z - type: string - tags: - description: Ticket tags - example: '["test","beta"]' - items: - type: string - type: array - ticketId: - description: Ticket ID - example: 1234 + usedSpaceTB: + description: Currently used space in TB. + example: 4 + format: double + type: number + usedSpacePercentage: + description: Currently used space in percentage. + example: 100 + format: double + maximum: 100 + minimum: 0 + type: number + numberOfObjects: + description: Number of all objects (i.e. files and folders) in object storage. + example: 2 format: int64 type: integer - type: - description: Ticket type - example: Incident - type: string required: - - createdDate - customerId - - description - - email - - isEscalated - - priority - - status - - subject - - tags + - numberOfObjects - tenantId - - ticketId - - type - - updatedDate - type: object - TicketCreateResponse: - example: - data: - - subject: New support ticket - description: Some details on the issue - updatedDate: 2023-11-14T10:22:48Z - priority: low - type: Incident - tags: '["test","beta"]' - createdDate: 2023-11-13T11:22:48Z - tenantId: DE - customerId: "54321" - isEscalated: false - email: test-customer@test.com - ticketId: 1234 - status: open - - subject: New support ticket - description: Some details on the issue - updatedDate: 2023-11-14T10:22:48Z - priority: low - type: Incident - tags: '["test","beta"]' - createdDate: 2023-11-13T11:22:48Z + - usedSpacePercentage + - usedSpaceTB + type: object + ObjectStoragesStatsResponse: + example: + data: + - usedSpaceTB: 4 + numberOfObjects: 2 + usedSpacePercentage: 100 + tenantId: DE + customerId: "54321" + - usedSpaceTB: 4 + numberOfObjects: 2 + usedSpacePercentage: 100 tenantId: DE customerId: "54321" - isEscalated: false - email: test-customer@test.com - ticketId: 1234 - status: open _links: - self: v1/tickets/123 + self: /v1/object-storages/stats/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 properties: data: items: - $ref: '#/components/schemas/TicketResponse' + $ref: '#/components/schemas/ObjectStoragesStatsResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: v1/tickets/123 + self: /v1/object-storages/stats/8cd3f2ba-65a7-4279-bb54-0fea88dc8860 required: - _links - data type: object - MetadataType: + CancelObjectStorageResponseData: example: + objectStorageId: objectStorageId + cancelDate: 2021-06-02T00:00:00.000+0000 + displayName: Object storage 1 tenantId: DE customerId: "54321" - name: type - availableChoices: '["Choice 1", "Choice 2"]' properties: tenantId: description: Your customer tenant id @@ -11970,423 +11378,627 @@ components: example: "54321" minLength: 1 type: string - name: - description: Type name - example: type + objectStorageId: + description: Object Storage id + type: string + cancelDate: + description: Cancellation date for object storage. + example: 2021-06-02 + format: date + type: string + displayName: + description: Display name for object storage. + example: Object storage 1 + maxLength: 255 + minLength: 1 type: string - availableChoices: - description: Available choices - example: '["Choice 1", "Choice 2"]' - items: - type: string - type: array required: - - availableChoices + - cancelDate - customerId - - name + - displayName + - objectStorageId - tenantId type: object - ListTicketMetadataResponse: + CancelObjectStorageResponse: example: data: - - tenantId: DE + - objectStorageId: objectStorageId + cancelDate: 2021-06-02T00:00:00.000+0000 + displayName: Object storage 1 + tenantId: DE customerId: "54321" - name: type - availableChoices: '["Choice 1", "Choice 2"]' - - tenantId: DE + - objectStorageId: objectStorageId + cancelDate: 2021-06-02T00:00:00.000+0000 + displayName: Object storage 1 + tenantId: DE customerId: "54321" - name: type - availableChoices: '["Choice 1", "Choice 2"]' _links: - self: v1/tickets/metadata + self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d properties: - data: - items: - $ref: '#/components/schemas/MetadataType' - type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: v1/tickets/metadata + self: /v1/object-storages/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + data: + items: + $ref: '#/components/schemas/CancelObjectStorageResponseData' + type: array required: - _links - data type: object - SecretResponse: + PatchObjectStorageRequest: example: - createdAt: 2021-06-03T06:27:12Z - tenantId: DE - customerId: "54321" - name: Password Secret - secretId: 12345 - type: password - value: password - updatedAt: 2021-06-03T06:27:12Z + displayName: Object storage 1 properties: - tenantId: - description: Your customer tenant id - example: DE + displayName: + description: Display name helps to differentiate between object storages, + especially if they are in the same region. + example: Object storage 1 + maxLength: 255 minLength: 1 type: string - customerId: - description: Your Customer number - example: "54321" + required: + - displayName + type: object + CreateTicketRequest: + example: + note: Note + sender: your@mail.com + subject: Subject + properties: + subject: + description: The ticket subject + example: Subject minLength: 1 type: string - secretId: - description: Secret's id - example: 12345 - minimum: 0 - type: number - name: - description: The name assigned to the password/ssh - example: Password Secret - maxLength: 255 + note: + description: The ticket note + example: Note minLength: 1 type: string - type: - description: The type of the secret. This will be available only when retrieving - secrets - enum: - - password - - ssh - example: password - maxLength: 500 + sender: + description: Customer email + example: your@mail.com minLength: 1 type: string - value: - description: The value of the secret. This will be available only when retrieving - a single secret - example: password - maxLength: 500 + required: + - note + - sender + - subject + type: object + CreateTicketResponseData: + example: + tenantId: DE + customerId: "54321" + properties: + tenantId: + description: Your customer tenant id + example: DE minLength: 1 type: string - createdAt: - description: The creation date for the secret - example: 2021-06-03T06:27:12Z - format: date-time - type: string - updatedAt: - description: The last update date for the secret - example: 2021-06-03T06:27:12Z - format: date-time + customerId: + description: Your customer number + example: "54321" + minLength: 1 type: string required: - - createdAt - customerId - - name - - secretId - tenantId - - type - - updatedAt - - value type: object - ListSecretResponse: + CreateTicketResponse: example: data: - - createdAt: 2021-06-03T06:27:12Z - tenantId: DE + - tenantId: DE customerId: "54321" - name: Password Secret - secretId: 12345 - type: password - value: password - updatedAt: 2021-06-03T06:27:12Z - - createdAt: 2021-06-03T06:27:12Z - tenantId: DE + - tenantId: DE customerId: "54321" - name: Password Secret - secretId: 12345 - type: password - value: password - updatedAt: 2021-06-03T06:27:12Z _links: - self: /v1/secrets - first: /v1/secrets?page=1 - previous: /v1/secrets?page=19 - next: /v1/secrets?page=21 - last: /v1/secrets?page=101 - _pagination: "" + self: /v1/create-ticket properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/SecretResponse' + $ref: '#/components/schemas/CreateTicketResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/secrets - first: /v1/secrets?page=1 - previous: /v1/secrets?page=19 - next: /v1/secrets?page=21 - last: /v1/secrets?page=101 + self: /v1/create-ticket required: - _links - - _pagination - data type: object - CreateSecretRequest: + ObjectStorageAuditResponse: example: - name: my-password - type: password - value: PwdA?2092w# + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + objectStorageId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + tenantId: DE + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe properties: - name: - description: The name of the secret that will keep the password - example: my-password - maxLength: 255 + id: + description: The identifier of the audit entry. + example: 12345 + format: int64 + type: integer + action: + description: Type of the action. + enum: + - CREATED + - UPDATED + - DELETED + example: CREATED + type: string + timestamp: + description: When the change took place. + example: 2021-03-30T11:35:06.177Z + format: date-time + type: string + tenantId: + description: Customer tenant id + example: DE minLength: 1 type: string - value: - description: 'The secret value that needs to be saved. In case of a password - it must match a pattern with at least one upper and lower case character - and either one number with two special characters `!@#$^&*?_~` or at least - three numbers with one special character `!@#$^&*?_~`. This is expressed - in the following regular expression: `^((?=.*?[A-Z]{1,})(?=.*?[a-z]{1,}))(((?=(?:[^d]*d){1})(?=([^^&*?_~]*[!@#$^&*?_~]){2,}))|((?=(?:[^d]*d){3})(?=.*?[!@#$^&*?_~]+))).{8,}$`' - example: PwdA?2092w# - minLength: 8 + customerId: + description: Customer number + example: "54321" + minLength: 1 type: string - type: - description: The type of the secret. Can be `password` or `ssh` - enum: - - password - - ssh - example: password + changedBy: + description: User ID + example: "54321" + minLength: 1 + type: string + username: + description: Name of the user which led to the change. + example: John.Doe + type: string + requestId: + description: The requestId of the API call which led to the change. + example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + type: string + traceId: + description: The traceId of the API call which led to the change. + example: 78E9A428-94E9-4A2A-92F5-26038C6884F + type: string + objectStorageId: + description: Object Storage Id + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 type: string + changes: + description: List of actual changes. + example: + prev: + name: test + new: + name: test1 + type: object required: - - name - - type - - value + - action + - changedBy + - customerId + - id + - objectStorageId + - requestId + - tenantId + - timestamp + - traceId + - username type: object - CreateSecretResponse: + ListObjectStorageAuditResponse: example: data: - - createdAt: 2021-06-03T06:27:12Z + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + objectStorageId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - name: Password Secret - secretId: 12345 - type: password - value: password - updatedAt: 2021-06-03T06:27:12Z - - createdAt: 2021-06-03T06:27:12Z + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + objectStorageId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - name: Password Secret - secretId: 12345 - type: password - value: password - updatedAt: 2021-06-03T06:27:12Z + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John.Doe _links: - self: /v1/secrets/123 + first: /v1/object-storages/audits?page=2 + previous: /v1/object-storages/audits?page=2 + next: /v1/object-storages/audits?page=3 + last: /v1/object-storages/audits?page=10 + self: /v1/object-storages/audits + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/SecretResponse' + $ref: '#/components/schemas/ObjectStorageAuditResponse' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/secrets/123 + first: /v1/object-storages/audits?page=2 + previous: /v1/object-storages/audits?page=2 + next: /v1/object-storages/audits?page=3 + last: /v1/object-storages/audits?page=10 + self: /v1/object-storages/audits required: - _links + - _pagination - data type: object - FindSecretResponse: + PrivateIpConfig: example: - data: - - createdAt: 2021-06-03T06:27:12Z - tenantId: DE - customerId: "54321" - name: Password Secret - secretId: 12345 - type: password - value: password - updatedAt: 2021-06-03T06:27:12Z - - createdAt: 2021-06-03T06:27:12Z - tenantId: DE - customerId: "54321" - name: Password Secret - secretId: 12345 - type: password - value: password - updatedAt: 2021-06-03T06:27:12Z - _links: - self: /v1/secrets/123 + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 properties: - data: + v4: items: - $ref: '#/components/schemas/SecretResponse' + $ref: '#/components/schemas/IpV4' type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/secrets/123 required: - - _links - - data + - v4 type: object - UpdateSecretRequest: + Instances: example: - name: name - value: value + ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok properties: + instanceId: + description: Instance id + example: 100 + format: int64 + type: integer + displayName: + description: Instance display name + example: Instance + type: string name: - description: The name of the secret to be saved + description: Instance name + example: vmd12345 type: string - value: - description: The value of the secret to be saved - minLength: 8 + productId: + description: Product id + example: V1 + type: string + privateIpConfig: + $ref: '#/components/schemas/PrivateIpConfig' + ipConfig: + $ref: '#/components/schemas/IpConfig' + status: + description: State of the instance in the Private Network + enum: + - ok + - restart + - reinstall + - reinstallation failed + - installing + example: ok + type: string + errorMessage: + description: Message in case of an error. type: string - type: object - UpdateSecretResponse: - example: - _links: - self: /v1/secrets/123 - properties: - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - description: Links for easy navigation. - example: - self: /v1/secrets/123 required: - - _links + - displayName + - instanceId + - ipConfig + - name + - privateIpConfig + - productId + - status type: object - SecretAuditResponse: + ListPrivateNetworkResponseData: example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - secretId: 12345 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU properties: - id: - description: The identifier of the audit entry. - example: 12345 - type: number - secretId: - description: Secret's id - example: 12345 - minimum: 0 - type: number - action: - description: Type of the action. - enum: - - CREATED - - UPDATED - - DELETED - example: CREATED - type: string - timestamp: - description: When the change took place. - example: 2021-03-30T11:35:06.177Z - format: date-time - type: string tenantId: - description: Customer tenant id + description: Your customer tenant id example: DE minLength: 1 type: string customerId: - description: Customer number + description: Your customer number example: "54321" minLength: 1 type: string - changedBy: - description: User ID - example: "54321" - minLength: 1 + privateNetworkId: + description: Private Network's id + example: 12345 + format: int64 + type: integer + dataCenter: + description: The data center where your Private Network is located + example: European Union (Germany) 1 type: string - username: - description: Name of the user which led to the change. - example: John Doe + region: + description: The slug of the region where your Private Network is located + example: EU type: string - requestId: - description: The requestId of the API call which led to the change. - example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + regionName: + description: The region where your Private Network is located + example: European Union (Germany) type: string - traceId: - description: The traceId of the API call which led to the change. - example: 78E9A428-94E9-4A2A-92F5-26038C6884F + name: + description: The name of the Private Network + example: myPrivateNetwork type: string - changes: - description: List of actual changes. - example: - prev: - name: test - new: - name: test1 - type: object + description: + description: The description of the Private Network + example: myPrivateNetwork Description + type: string + cidr: + description: The cidr range of the Private Network + example: 10.0.0.0/22 + type: string + availableIps: + description: The total available IPs of the Private Network + example: 1022 + format: int64 + type: integer + createdDate: + description: The creation date of the Private Network + example: 2021-06-03T06:27:12Z + format: date-time + type: string + instances: + items: + $ref: '#/components/schemas/Instances' + type: array required: - - action - - changedBy + - availableIps + - cidr + - createdDate - customerId - - id - - requestId - - secretId + - dataCenter + - description + - instances + - name + - privateNetworkId + - region + - regionName - tenantId - - timestamp - - traceId - - username type: object - ListSecretAuditResponse: + ListPrivateNetworkResponse: example: data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - secretId: 12345 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - changedBy: "54321" - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - secretId: 12345 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John Doe + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU _links: - first: /v1/secrets/audits?page=1 - previous: /v1/secrets/audits?page=19 - self: /v1/secrets/audits?page=20 - next: /v1/secrets/audits?page=21 - last: /v1/secrets/audits?page=101 + first: /v1/private-networks?page=1 + previous: /v1/private-networks?page=19 + self: /v1/private-networks?page=20 + next: /v1/private-networks?page=21 + last: /v1/private-networks?page=101 _pagination: "" properties: _pagination: @@ -12395,87 +12007,112 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/SecretAuditResponse' + $ref: '#/components/schemas/ListPrivateNetworkResponseData' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/secrets/audits?page=1 - previous: /v1/secrets/audits?page=19 - self: /v1/secrets/audits?page=20 - next: /v1/secrets/audits?page=21 - last: /v1/secrets/audits?page=101 + first: /v1/private-networks?page=1 + previous: /v1/private-networks?page=19 + self: /v1/private-networks?page=20 + next: /v1/private-networks?page=21 + last: /v1/private-networks?page=101 required: - _links - _pagination - data type: object - InstanceStartActionResponseData: + CreatePrivateNetworkRequest: example: - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start + name: myPrivateNetwork + description: myPrivateNetwork Description + region: EU properties: - tenantId: - description: Your customer tenant id - example: DE + region: + default: EU + description: Region where the Private Network should be located. Default + is `EU` + example: EU minLength: 1 type: string - customerId: - description: Your customer number - example: "54321" + name: + description: The name of the Private Network. It may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + Private Network name. + example: myPrivateNetwork + maxLength: 255 minLength: 1 type: string - instanceId: - description: Compute instance / resource id - example: 12345 - format: int64 - type: integer - action: - description: Action that was triggered - example: start + description: + description: The description of the Private Network. There is a limit of + 255 characters per Private Network description. + example: myPrivateNetwork Description + maxLength: 255 type: string required: - - action - - customerId - - instanceId - - tenantId - type: object - InstanceStartActionResponse: - example: - data: - - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start - - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start - _links: - self: /v1/compute/instances/12345/actions/start - properties: - data: - items: - $ref: '#/components/schemas/InstanceStartActionResponseData' - type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/compute/instances/12345/actions/start - required: - - _links - - data + - name type: object - InstanceRestartActionResponseData: + PrivateNetworkResponse: example: - instanceId: 12345 + createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - action: start + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU properties: tenantId: description: Your customer tenant id @@ -12487,1086 +12124,1145 @@ components: example: "54321" minLength: 1 type: string - instanceId: - description: Compute instance / resource id + privateNetworkId: + description: Private Network's id example: 12345 format: int64 type: integer - action: - description: Action that was triggered - example: start + dataCenter: + description: The data center where your Private Network is located + example: European Union (Germany) 1 + type: string + region: + description: The slug of the region where your Private Network is located + example: EU + type: string + regionName: + description: The region where your Private Network is located + example: European Union (Germany) + type: string + name: + description: The name of the Private Network + example: myPrivateNetwork + type: string + description: + description: The description of the Private Network + example: myPrivateNetwork Description + type: string + cidr: + description: The cidr range of the Private Network + example: 10.0.0.0/22 + type: string + availableIps: + description: The total available IPs of the Private Network + example: 1022 + format: int64 + type: integer + createdDate: + description: The creation date of the Private Network + example: 2021-06-03T06:27:12Z + format: date-time type: string + instances: + items: + $ref: '#/components/schemas/Instances' + type: array required: - - action + - availableIps + - cidr + - createdDate - customerId - - instanceId + - dataCenter + - description + - instances + - name + - privateNetworkId + - region + - regionName - tenantId type: object - InstanceRestartActionResponse: + CreatePrivateNetworkResponse: example: data: - - instanceId: 12345 + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - action: start - - instanceId: 12345 + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - action: start + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU _links: - self: /v1/compute/instances/12345/actions/restart + self: /v1/private-networks/12345 properties: data: items: - $ref: '#/components/schemas/InstanceRestartActionResponseData' + $ref: '#/components/schemas/PrivateNetworkResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345/actions/restart + self: /v1/private-networks/12345 required: - _links - data type: object - InstanceStopActionResponseData: + PatchPrivateNetworkRequest: example: - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start + name: myPrivateNetwork + description: myPrivateNetwork Description properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: "54321" + name: + description: The name of the Private Network. It may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + Private Network. + example: myPrivateNetwork + maxLength: 255 minLength: 1 type: string - instanceId: - description: Compute instance / resource id - example: 12345 - format: int64 - type: integer - action: - description: Action that was triggered - example: start + description: + description: The description of the Private Network. There is a limit of + 255 characters per Private Network. + example: myPrivateNetwork Description + maxLength: 255 type: string - required: - - action - - customerId - - instanceId - - tenantId type: object - InstanceStopActionResponse: + PatchPrivateNetworkResponse: example: data: - - instanceId: 12345 + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - action: start - - instanceId: 12345 + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - action: start + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU _links: - self: /v1/compute/instances/12345/actions/stop + self: /v1/private-networks/12345 properties: data: items: - $ref: '#/components/schemas/InstanceStopActionResponseData' + $ref: '#/components/schemas/PrivateNetworkResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345/actions/stop + self: /v1/private-networks/12345 required: - _links - data type: object - InstanceShutdownActionResponseData: - example: - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start - properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 - type: string - instanceId: - description: Compute instance / resource id - example: 12345 - format: int64 - type: integer - action: - description: Action that was triggered - example: start - type: string - required: - - action - - customerId - - instanceId - - tenantId - type: object - InstanceShutdownActionResponse: + FindPrivateNetworkResponse: example: data: - - instanceId: 12345 + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - action: start - - instanceId: 12345 + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU + - createdDate: 2021-06-03T06:27:12Z + privateNetworkId: 12345 + dataCenter: European Union (Germany) 1 + availableIps: 1022 + instances: + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + - ipConfig: + v6: + netmaskCidr: 64 + ip: 1:2:3:4:5:6:7:8 + gateway: 1:2:3:4:5:6:7:8 + v4: + netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + instanceId: 100 + productId: V1 + displayName: Instance + name: vmd12345 + errorMessage: errorMessage + privateIpConfig: + v4: + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + - netmaskCidr: 19 + ip: 192.168.0.1 + gateway: 1.1.1.1 + status: ok + regionName: European Union (Germany) tenantId: DE customerId: "54321" - action: start + name: myPrivateNetwork + description: myPrivateNetwork Description + cidr: 10.0.0.0/22 + region: EU _links: - self: /v1/compute/instances/12345/actions/shutdown + self: /v1/private-networks/12345 properties: data: items: - $ref: '#/components/schemas/InstanceShutdownActionResponseData' + $ref: '#/components/schemas/PrivateNetworkResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345/actions/shutdown + self: /v1/private-networks/12345 required: - _links - data type: object - InstancesActionsRescueRequest: - example: - userData: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ - ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ - \ \n expire: False\n" - sshKeys: '[123, 125]' - rootPassword: 1 - properties: - rootPassword: - description: '`secretId` of the password to login into rescue system for - the `root` user.' - example: 1 - format: int64 - type: integer - sshKeys: - description: Array of `secretId`s of public SSH keys for logging into rescue - system as `root` user. - example: '[123, 125]' - items: - format: int64 - type: integer - type: array - userData: - description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize - during start of compute instance.' - example: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ - ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ - \ \n expire: False\n" - type: string - type: object - InstanceRescueActionResponseData: - example: - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start + InstanceAssignmentSelfLinks: properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 + self: + description: Link to current resource. type: string - customerId: - description: Your customer number - example: "54321" - minLength: 1 + virtualPrivateCloud: + description: Link to related Private Network. type: string - instanceId: - description: Compute instance / resource id - example: 12345 - format: int64 - type: integer - action: - description: Action that was triggered - example: start + instance: + description: Link to assigned instance. type: string required: - - action - - customerId - - instanceId - - tenantId + - instance + - self + - virtualPrivateCloud type: object - InstanceRescueActionResponse: + AssignInstancePrivateNetworkResponse: example: - data: - - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start - - instanceId: 12345 - tenantId: DE - customerId: "54321" - action: start _links: - self: /v1/compute/instances/12345/actions/rescue + self: /v1/private-networks/12345/instances/100 + virtualPrivateCloud: /v1/private-networks/12345 + instance: /v1/compute/instances/100 properties: - data: - items: - $ref: '#/components/schemas/InstanceRescueActionResponseData' - type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/InstanceAssignmentSelfLinks' + description: Links for easy navigation. example: - self: /v1/compute/instances/12345/actions/rescue + self: /v1/private-networks/12345/instances/100 + virtualPrivateCloud: /v1/private-networks/12345 + instance: /v1/compute/instances/100 required: - _links - - data type: object - InstancesResetPasswordActionsRequest: + UnassignInstancePrivateNetworkResponse: example: - userData: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ - ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ - \ \n expire: False\n" - sshKeys: '[123, 125]' - rootPassword: 1 + _links: + self: /v1/private-networks/12345/instances/100 + virtualPrivateCloud: /v1/private-networks/12345 + instance: /v1/compute/instances/100 properties: - sshKeys: - description: Array of `secretId`s of public SSH keys for logging into as - `defaultUser` with administrator/root privileges. Applies to Linux/BSD - systems. Please refer to Secrets Management API. - example: '[123, 125]' - items: - format: int64 - type: integer - type: array - rootPassword: - description: '`secretId` of the password for the `defaultUser` with administrator/root - privileges. For Linux/BSD please use SSH, for Windows RDP. Please refer - to Secrets Management API.' - example: 1 - format: int64 - type: integer - userData: - description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize - during start of compute instance.' - example: "#cloud-config\nuser: root\nssh_pwauth: true\ndisable_root: false\n\ - ssh_authorized_keys:\n - \nchpasswd:\n list:\n - root:\ - \ \n expire: False\n" - type: string + _links: + allOf: + - $ref: '#/components/schemas/InstanceAssignmentSelfLinks' + description: Links for easy navigation. + example: + self: /v1/private-networks/12345/instances/100 + virtualPrivateCloud: /v1/private-networks/12345 + instance: /v1/compute/instances/100 + required: + - _links type: object - InstanceResetPasswordActionResponseData: + PrivateNetworkAuditResponse: example: - instanceId: 12345 + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + privateNetworkId: 12345 + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - action: start + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John Doe properties: + id: + description: The identifier of the audit entry. + example: 12345 + format: int64 + type: integer + privateNetworkId: + description: The identifier of the Private Network + example: 12345 + minimum: 0 + type: number + action: + description: Type of the action. + enum: + - CREATED + - DELETED + - UPDATED + example: CREATED + type: string + timestamp: + description: When the change took place. + example: 2021-03-30T11:35:06.177Z + format: date-time + type: string tenantId: - description: Your customer tenant id + description: Customer tenant id example: DE minLength: 1 type: string customerId: - description: Your customer number + description: Customer number example: "54321" minLength: 1 type: string - instanceId: - description: Compute instance / resource id - example: 12345 - format: int64 - type: integer - action: - description: Action that was triggered - example: start + changedBy: + description: User id + example: "54321" + minLength: 1 + type: string + username: + description: User name which did the change. + example: John Doe + type: string + requestId: + description: The requestId of the API call which led to the change. + example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + type: string + traceId: + description: The traceId of the API call which led to the change. + example: 78E9A428-94E9-4A2A-92F5-26038C6884F type: string + changes: + description: List of actual changes. + example: + prev: + name: test + new: + name: test1 + type: object required: - action + - changedBy - customerId - - instanceId + - id + - privateNetworkId + - requestId - tenantId + - timestamp + - traceId + - username type: object - InstanceResetPasswordActionResponse: + ListPrivateNetworkAuditResponse: example: data: - - instanceId: 12345 + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + privateNetworkId: 12345 + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - action: start - - instanceId: 12345 + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + privateNetworkId: 12345 + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" - action: start + changes: + prev: + name: test + new: + name: test1 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John Doe _links: - self: /v1/compute/instances/12345/actions/resetPassword + first: /v1/private-networks/audits?page=2 + previous: /v1/private-networks/audits?page=2 + next: /v1/private-networks/audits?page=3 + last: /v1/private-networks/audits?page=10 + self: /v1/private-networks/audits + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/InstanceResetPasswordActionResponseData' + $ref: '#/components/schemas/PrivateNetworkAuditResponse' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/compute/instances/12345/actions/resetPassword - required: - - _links - - data - type: object - AdditionalIp: - example: - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - properties: - v4: - $ref: '#/components/schemas/IpV4' - required: - - v4 - type: object - instanceStatus: - enum: - - provisioning - - uninstalled - - running - - stopped - - error - - installing - - unknown - - manual_provisioning - - product_not_available - - verification_required - - rescue - - pending_payment - - other - type: string - AddOnResponse: - example: - quantity: 4 - id: 1431 - properties: - id: - description: Id of the Addon. Please refer to list [here](https://contabo.com/en/product-list/?show_ids=true). - example: 1431 - format: int64 - type: integer - quantity: - description: The number of Addons you wish to aquire. - example: 4 - format: int64 - type: integer + first: /v1/private-networks/audits?page=2 + previous: /v1/private-networks/audits?page=2 + next: /v1/private-networks/audits?page=3 + last: /v1/private-networks/audits?page=10 + self: /v1/private-networks/audits required: - - id - - quantity + - _links + - _pagination + - data type: object - ListInstancesResponseData: + SecretResponse: example: - cancelDate: 2021-06-03T00:00:00.000+0000 - displayName: VPS - regionName: European Union (Germany) - productName: VPS M - instanceId: 100 - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - osType: Linux - defaultUser: root - sshKeys: - - 123 - - 125 - productType: ssd - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V5 - dataCenter: European Union (Germany) 1 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 - ramMb: 1024 - errorMessage: errorMessage - additionalIps: - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - diskMb: 2048 - macAddress: F2:65:50:F3:63:A1 - createdDate: 2021-06-03T06:27:12Z - cpuCores: 4 - vHostId: 73395 + createdAt: 2021-06-03T06:27:12Z tenantId: DE - name: vmd12345 - region: EU + customerId: "54321" + name: Password Secret + secretId: 12345 + type: password + value: password + updatedAt: 2021-06-03T06:27:12Z properties: tenantId: description: Your customer tenant id - enum: - - DE - - INT example: DE minLength: 1 type: string customerId: - description: Customer ID - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + description: Your Customer number + example: "54321" minLength: 1 type: string - additionalIps: - items: - $ref: '#/components/schemas/AdditionalIp' - type: array + secretId: + description: Secret's id + example: 12345 + minimum: 0 + type: number name: - description: Instance Name - example: vmd12345 - type: string - displayName: - description: Instance display name - example: VPS - type: string - instanceId: - description: Instance ID - example: 100 - format: int64 - type: integer - dataCenter: - description: The data center where your Private Network is located - example: European Union (Germany) 1 - type: string - region: - description: Instance region where the compute instance should be located. - example: EU - type: string - regionName: - description: The name of the region where the instance is located. - example: European Union (Germany) - type: string - productId: - description: Product ID - example: V5 - type: string - imageId: - description: Image's id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + description: The name assigned to the password/ssh + example: Password Secret + maxLength: 255 + minLength: 1 type: string - ipConfig: - $ref: '#/components/schemas/IpConfig' - macAddress: - description: MAC Address - example: F2:65:50:F3:63:A1 + type: + description: The type of the secret. This will be available only when retrieving + secrets + enum: + - password + - ssh + example: password + maxLength: 500 + minLength: 1 type: string - ramMb: - description: Image RAM size in MB - example: 1024 - type: number - cpuCores: - description: CPU core count - example: 4 - format: int64 - type: integer - osType: - description: Type of operating system (OS) - example: Linux + value: + description: The value of the secret. This will be available only when retrieving + a single secret + example: password + maxLength: 500 + minLength: 1 type: string - diskMb: - description: Image Disk size in MB - example: 2048 - type: number - sshKeys: - description: Array of `secretId`s of public SSH keys for logging into as - `defaultUser` with administrator/root privileges. Applies to Linux/BSD - systems. Please refer to Secrets Management API. - example: - - 123 - - 125 - items: - format: int64 - type: integer - type: array - createdDate: - description: The creation date for the instance + createdAt: + description: The creation date for the secret example: 2021-06-03T06:27:12Z format: date-time type: string - cancelDate: - description: The date on which the instance will be cancelled - example: 2021-06-03 - format: date - maxLength: 10 - minLength: 0 - pattern: yyyy-mm-dd + updatedAt: + description: The last update date for the secret + example: 2021-06-03T06:27:12Z + format: date-time type: string - status: - $ref: '#/components/schemas/instanceStatus' - vHostId: - description: ID of host system - example: 73395 - format: int64 - type: integer - addOns: + required: + - createdAt + - customerId + - name + - secretId + - tenantId + - type + - updatedAt + - value + type: object + ListSecretResponse: + example: + data: + - createdAt: 2021-06-03T06:27:12Z + tenantId: DE + customerId: "54321" + name: Password Secret + secretId: 12345 + type: password + value: password + updatedAt: 2021-06-03T06:27:12Z + - createdAt: 2021-06-03T06:27:12Z + tenantId: DE + customerId: "54321" + name: Password Secret + secretId: 12345 + type: password + value: password + updatedAt: 2021-06-03T06:27:12Z + _links: + self: /v1/secrets + first: /v1/secrets?page=1 + previous: /v1/secrets?page=19 + next: /v1/secrets?page=21 + last: /v1/secrets?page=101 + _pagination: "" + properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. + data: items: - $ref: '#/components/schemas/AddOnResponse' + $ref: '#/components/schemas/SecretResponse' type: array - errorMessage: - description: Message in case of an error. - type: string - productType: - description: Instance's category depending on Product Id - enum: - - hdd - - ssd - - vds - - nvme - example: ssd + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + example: + self: /v1/secrets + first: /v1/secrets?page=1 + previous: /v1/secrets?page=19 + next: /v1/secrets?page=21 + last: /v1/secrets?page=101 + required: + - _links + - _pagination + - data + type: object + CreateSecretRequest: + example: + name: my-password + type: password + value: PwdA?2092w# + properties: + name: + description: The name of the secret that will keep the password + example: my-password + maxLength: 255 + minLength: 1 type: string - productName: - description: Instance's Product Name - example: VPS M + value: + description: 'The secret value that needs to be saved. In case of a password + it must match a pattern with at least one upper and lower case character + and either one number with two special characters `!@#$^&*?_~` or at least + three numbers with one special character `!@#$^&*?_~`. This is expressed + in the following regular expression: `^((?=.*?[A-Z]{1,})(?=.*?[a-z]{1,}))(((?=(?:[^d]*d){1})(?=([^^&*?_~]*[!@#$^&*?_~]){2,}))|((?=(?:[^d]*d){3})(?=.*?[!@#$^&*?_~]+))).{8,}$`' + example: PwdA?2092w# + minLength: 8 type: string - defaultUser: - description: Default user name created for login during (re-)installation - with administrative privileges. Allowed values for Linux/BSD are `admin` - (use sudo to apply administrative privileges like root) or `root`. Allowed - values for Windows are `admin` (has administrative privileges like administrator) - or `administrator`. + type: + description: The type of the secret. Can be `password` or `ssh` enum: - - root - - admin - - administrator - example: root + - password + - ssh + example: password type: string required: - - addOns - - additionalIps - - cancelDate - - cpuCores - - createdDate - - customerId - - dataCenter - - diskMb - - displayName - - imageId - - instanceId - - ipConfig - - macAddress - name - - osType - - productId - - productName - - productType - - ramMb - - region - - regionName - - sshKeys - - status - - tenantId - - vHostId + - type + - value type: object - ListInstancesResponse: + CreateSecretResponse: example: data: - - cancelDate: 2021-06-03T00:00:00.000+0000 - displayName: VPS - regionName: European Union (Germany) - productName: VPS M - instanceId: 100 - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - osType: Linux - defaultUser: root - sshKeys: - - 123 - - 125 - productType: ssd - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V5 - dataCenter: European Union (Germany) 1 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 - ramMb: 1024 - errorMessage: errorMessage - additionalIps: - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - diskMb: 2048 - macAddress: F2:65:50:F3:63:A1 - createdDate: 2021-06-03T06:27:12Z - cpuCores: 4 - vHostId: 73395 + - createdAt: 2021-06-03T06:27:12Z tenantId: DE - name: vmd12345 - region: EU - - cancelDate: 2021-06-03T00:00:00.000+0000 - displayName: VPS - regionName: European Union (Germany) - productName: VPS M - instanceId: 100 - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - osType: Linux - defaultUser: root - sshKeys: - - 123 - - 125 - productType: ssd - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V5 - dataCenter: European Union (Germany) 1 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 - ramMb: 1024 - errorMessage: errorMessage - additionalIps: - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - diskMb: 2048 - macAddress: F2:65:50:F3:63:A1 - createdDate: 2021-06-03T06:27:12Z - cpuCores: 4 - vHostId: 73395 + customerId: "54321" + name: Password Secret + secretId: 12345 + type: password + value: password + updatedAt: 2021-06-03T06:27:12Z + - createdAt: 2021-06-03T06:27:12Z tenantId: DE - name: vmd12345 - region: EU + customerId: "54321" + name: Password Secret + secretId: 12345 + type: password + value: password + updatedAt: 2021-06-03T06:27:12Z _links: - first: /v1/compute/instances?page=1 - previous: /v1/compute/instances?page=19 - self: /v1/compute/instances?page=20 - next: /v1/compute/instances?page=21 - last: /v1/compute/instances?page=101 - _pagination: "" + self: /v1/secrets/123 properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/ListInstancesResponseData' + $ref: '#/components/schemas/SecretResponse' type: array _links: allOf: - - $ref: '#/components/schemas/Links' + - $ref: '#/components/schemas/SelfLinks' example: - first: /v1/compute/instances?page=1 - previous: /v1/compute/instances?page=19 - self: /v1/compute/instances?page=20 - next: /v1/compute/instances?page=21 - last: /v1/compute/instances?page=101 + self: /v1/secrets/123 required: - _links - - _pagination - data type: object - InstanceResponse: + FindSecretResponse: example: - cancelDate: 2021-06-03T00:00:00.000+0000 - displayName: VPS - regionName: European Union (Germany) - productName: VPS M - instanceId: 100 - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - osType: Linux - defaultUser: root - sshKeys: - - 123 - - 125 - productType: ssd - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V5 - dataCenter: European Union (Germany) 1 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 - ramMb: 1024 - errorMessage: errorMessage - additionalIps: - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - diskMb: 2048 - macAddress: F2:65:50:F3:63:A1 - createdDate: 2021-06-03T06:27:12Z - cpuCores: 4 - vHostId: 73395 - tenantId: DE - name: vmd12345 - region: EU + data: + - createdAt: 2021-06-03T06:27:12Z + tenantId: DE + customerId: "54321" + name: Password Secret + secretId: 12345 + type: password + value: password + updatedAt: 2021-06-03T06:27:12Z + - createdAt: 2021-06-03T06:27:12Z + tenantId: DE + customerId: "54321" + name: Password Secret + secretId: 12345 + type: password + value: password + updatedAt: 2021-06-03T06:27:12Z + _links: + self: /v1/secrets/123 properties: - tenantId: - description: Your customer tenant id - enum: - - DE - - INT - example: DE - minLength: 1 - type: string - customerId: - description: Customer ID - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - minLength: 1 - type: string - additionalIps: + data: items: - $ref: '#/components/schemas/AdditionalIp' + $ref: '#/components/schemas/SecretResponse' type: array + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + example: + self: /v1/secrets/123 + required: + - _links + - data + type: object + UpdateSecretRequest: + example: + name: name + value: value + properties: name: - description: Instance Name - example: vmd12345 - type: string - displayName: - description: Instance display name - example: VPS - type: string - instanceId: - description: Instance ID - example: 100 - format: int64 - type: integer - dataCenter: - description: The data center where your Private Network is located - example: European Union (Germany) 1 - type: string - region: - description: Instance region where the compute instance should be located. - example: EU - type: string - regionName: - description: The name of the region where the instance is located. - example: European Union (Germany) - type: string - productId: - description: Product ID - example: V5 - type: string - imageId: - description: Image's id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + description: The name of the secret to be saved type: string - ipConfig: - $ref: '#/components/schemas/IpConfig' - macAddress: - description: MAC Address - example: F2:65:50:F3:63:A1 + value: + description: The value of the secret to be saved + minLength: 8 type: string - ramMb: - description: Image RAM size in MB - example: 1024 + type: object + UpdateSecretResponse: + example: + _links: + self: /v1/secrets/123 + properties: + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + description: Links for easy navigation. + example: + self: /v1/secrets/123 + required: + - _links + type: object + SecretAuditResponse: + example: + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + tenantId: DE + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + secretId: 12345 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John Doe + properties: + id: + description: The identifier of the audit entry. + example: 12345 type: number - cpuCores: - description: CPU core count - example: 4 - format: int64 - type: integer - osType: - description: Type of operating system (OS) - example: Linux - type: string - diskMb: - description: Image Disk size in MB - example: 2048 + secretId: + description: Secret's id + example: 12345 + minimum: 0 type: number - sshKeys: - description: Array of `secretId`s of public SSH keys for logging into as - `defaultUser` with administrator/root privileges. Applies to Linux/BSD - systems. Please refer to Secrets Management API. - example: - - 123 - - 125 - items: - format: int64 - type: integer - type: array - createdDate: - description: The creation date for the instance - example: 2021-06-03T06:27:12Z + action: + description: Type of the action. + enum: + - CREATED + - UPDATED + - DELETED + example: CREATED + type: string + timestamp: + description: When the change took place. + example: 2021-03-30T11:35:06.177Z format: date-time type: string - cancelDate: - description: The date on which the instance will be cancelled - example: 2021-06-03 - format: date - maxLength: 10 - minLength: 0 - pattern: yyyy-mm-dd + tenantId: + description: Customer tenant id + example: DE + minLength: 1 type: string - status: - $ref: '#/components/schemas/instanceStatus' - vHostId: - description: ID of host system - example: 73395 - format: int64 - type: integer - addOns: - items: - $ref: '#/components/schemas/AddOnResponse' - type: array - errorMessage: - description: Message in case of an error. + customerId: + description: Customer number + example: "54321" + minLength: 1 type: string - productType: - description: Instance's category depending on Product Id - enum: - - hdd - - ssd - - vds - - nvme - example: ssd + changedBy: + description: User ID + example: "54321" + minLength: 1 type: string - productName: - description: Instance's Product Name - example: VPS M + username: + description: Name of the user which led to the change. + example: John Doe type: string - defaultUser: - description: Default user name created for login during (re-)installation - with administrative privileges. Allowed values for Linux/BSD are `admin` - (use sudo to apply administrative privileges like root) or `root`. Allowed - values for Windows are `admin` (has administrative privileges like administrator) - or `administrator`. - enum: - - root - - admin - - administrator - example: root + requestId: + description: The requestId of the API call which led to the change. + example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + type: string + traceId: + description: The traceId of the API call which led to the change. + example: 78E9A428-94E9-4A2A-92F5-26038C6884F type: string + changes: + description: List of actual changes. + example: + prev: + name: test + new: + name: test1 + type: object required: - - addOns - - additionalIps - - cancelDate - - cpuCores - - createdDate + - action + - changedBy - customerId - - dataCenter - - diskMb - - displayName - - imageId - - instanceId - - ipConfig - - macAddress - - name - - osType - - productId - - productName - - productType - - ramMb - - region - - regionName - - sshKeys - - status + - id + - requestId + - secretId - tenantId - - vHostId + - timestamp + - traceId + - username type: object - FindInstanceResponse: + ListSecretAuditResponse: example: data: - - cancelDate: 2021-06-03T00:00:00.000+0000 - displayName: VPS - regionName: European Union (Germany) - productName: VPS M - instanceId: 100 - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - osType: Linux - defaultUser: root - sshKeys: - - 123 - - 125 - productType: ssd - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V5 - dataCenter: European Union (Germany) 1 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 - ramMb: 1024 - errorMessage: errorMessage - additionalIps: - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - diskMb: 2048 - macAddress: F2:65:50:F3:63:A1 - createdDate: 2021-06-03T06:27:12Z - cpuCores: 4 - vHostId: 73395 + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE - name: vmd12345 - region: EU - - cancelDate: 2021-06-03T00:00:00.000+0000 - displayName: VPS - regionName: European Union (Germany) - productName: VPS M - instanceId: 100 - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - osType: Linux - defaultUser: root - sshKeys: - - 123 - - 125 - productType: ssd - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V5 - dataCenter: European Union (Germany) 1 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 - ramMb: 1024 - errorMessage: errorMessage - additionalIps: - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - ipConfig: - v6: - netmaskCidr: 64 - ip: 1:2:3:4:5:6:7:8 - gateway: 1:2:3:4:5:6:7:8 - v4: - netmaskCidr: 19 - ip: 192.168.0.1 - gateway: 1.1.1.1 - diskMb: 2048 - macAddress: F2:65:50:F3:63:A1 - createdDate: 2021-06-03T06:27:12Z - cpuCores: 4 - vHostId: 73395 + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + secretId: 12345 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F + changedBy: "54321" + requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE - name: vmd12345 - region: EU + customerId: "54321" + changes: + prev: + name: test + new: + name: test1 + secretId: 12345 + action: CREATED + id: 12345 + timestamp: 2021-03-30T11:35:06.177Z + username: John Doe _links: - self: /v1/compute/instances/100 + first: /v1/secrets/audits?page=1 + previous: /v1/secrets/audits?page=19 + self: /v1/secrets/audits?page=20 + next: /v1/secrets/audits?page=21 + last: /v1/secrets/audits?page=101 + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/InstanceResponse' + $ref: '#/components/schemas/SecretAuditResponse' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/compute/instances/100 + first: /v1/secrets/audits?page=1 + previous: /v1/secrets/audits?page=19 + self: /v1/secrets/audits?page=20 + next: /v1/secrets/audits?page=21 + last: /v1/secrets/audits?page=101 required: - _links + - _pagination - data type: object - PatchInstanceRequest: + TicketCreateRequest: example: - displayName: VPS - vncEnabled: true + assignedGroup: Support + sourceClient: Website + subject: New support ticket + description: Some details on the issue + type: Incident + tags: '["test","beta"]' properties: - displayName: - description: The display name of the instance - example: VPS - maxLength: 255 + description: + description: Ticket description + example: Some details on the issue type: string - vncEnabled: - description: Enable/Disable the VNC option for instance - example: true - type: boolean + subject: + description: Ticket subject + example: New support ticket + type: string + tags: + description: Ticket tags + example: '["test","beta"]' + items: + type: string + type: array + type: + description: Ticket type + example: Incident + type: string + assignedGroup: + description: Ticket Group + example: Support + type: string + sourceClient: + description: Ticket Source + example: Website + type: string + required: + - description + - sourceClient + - subject + - type type: object - PatchInstanceResponseData: + TicketResponse: example: - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z + subject: New support ticket + description: Some details on the issue + updatedDate: 2023-11-14T10:22:48Z + priority: low + type: Incident + tags: '["test","beta"]' + createdDate: 2023-11-13T11:22:48Z tenantId: DE customerId: "54321" + isEscalated: false + email: test-customer@test.com + ticketId: 1234 + status: open properties: tenantId: description: Your customer tenant id @@ -13578,119 +13274,129 @@ components: example: "54321" minLength: 1 type: string - instanceId: - description: Instance's id - example: 12345 + email: + description: Ticket email + example: test-customer@test.com + type: string + isEscalated: + description: Ticket escalated flag + example: false + type: boolean + priority: + description: Ticket priority + enum: + - low + - medium + - high + - urgent + example: low + type: string + status: + description: Ticket status + enum: + - open + - pending + - resolved + - closed + example: open + type: string + subject: + description: Ticket subject + example: New support ticket + type: string + description: + description: Ticket description + example: Some details on the issue + type: string + createdDate: + description: Created Date + example: 2023-11-13T11:22:48Z + type: string + updatedDate: + description: Created Date + example: 2023-11-14T10:22:48Z + type: string + tags: + description: Ticket tags + example: '["test","beta"]' + items: + type: string + type: array + ticketId: + description: Ticket ID + example: 1234 format: int64 type: integer - createdDate: - description: Creation date of the instance - example: 2021-06-02T12:32:03.363Z - format: date-time + type: + description: Ticket type + example: Incident type: string required: - createdDate - customerId - - instanceId + - description + - email + - isEscalated + - priority + - status + - subject + - tags - tenantId + - ticketId + - type + - updatedDate type: object - PatchInstanceResponse: + TicketCreateResponse: example: data: - - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z + - subject: New support ticket + description: Some details on the issue + updatedDate: 2023-11-14T10:22:48Z + priority: low + type: Incident + tags: '["test","beta"]' + createdDate: 2023-11-13T11:22:48Z tenantId: DE customerId: "54321" - - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z + isEscalated: false + email: test-customer@test.com + ticketId: 1234 + status: open + - subject: New support ticket + description: Some details on the issue + updatedDate: 2023-11-14T10:22:48Z + priority: low + type: Incident + tags: '["test","beta"]' + createdDate: 2023-11-13T11:22:48Z tenantId: DE customerId: "54321" + isEscalated: false + email: test-customer@test.com + ticketId: 1234 + status: open _links: - self: /v1/compute/instances/12345 + self: v1/tickets/123 properties: data: items: - $ref: '#/components/schemas/PatchInstanceResponseData' + $ref: '#/components/schemas/TicketResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345 + self: v1/tickets/123 required: - _links - data type: object - ReinstallInstanceRequest: - example: - imageId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - userData: |- - #cloud-config - user: admin - timezone: Europe/Berlin - chpasswd: - expire: False - defaultUser: root - sshKeys: '[123, 125]' - applicationId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - rootPassword: 1 - properties: - imageId: - description: ImageId to be used to setup the compute instance. - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - type: string - sshKeys: - description: Array of `secretId`s of public SSH keys for logging into as - `defaultUser` with administrator/root privileges. Applies to Linux/BSD - systems. Please refer to Secrets Management API. - example: '[123, 125]' - items: - format: int64 - type: integer - type: array - rootPassword: - description: '`secretId` of the password for the `defaultUser` with administrator/root - privileges. For Linux/BSD please use SSH, for Windows RDP. Please refer - to Secrets Management API.' - example: 1 - format: int64 - type: integer - userData: - description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize - during start of compute instance.' - example: |- - #cloud-config - user: admin - timezone: Europe/Berlin - chpasswd: - expire: False - type: string - defaultUser: - default: admin - description: Default user name created for login during (re-)installation - with administrative privileges. Allowed values for Linux/BSD are `admin` - (use sudo to apply administrative privileges like root) or `root`. Allowed - values for Windows are `admin` (has administrative privileges like administrator) - or `administrator`. - enum: - - root - - admin - - administrator - example: root - type: string - applicationId: - description: Application ID - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - type: string - required: - - imageId - type: object - ReinstallInstanceResponseData: + MetadataType: example: - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z tenantId: DE customerId: "54321" + name: type + availableChoices: '["Choice 1", "Choice 2"]' properties: tenantId: description: Your customer tenant id @@ -13702,279 +13408,162 @@ components: example: "54321" minLength: 1 type: string - instanceId: - description: Instance's id - example: 12345 - format: int64 - type: integer - createdDate: - description: Creation date for instance - example: 2021-06-02T12:32:03.363Z - format: date-time + name: + description: Type name + example: type type: string + availableChoices: + description: Available choices + example: '["Choice 1", "Choice 2"]' + items: + type: string + type: array required: - - createdDate + - availableChoices - customerId - - instanceId + - name - tenantId type: object - ReinstallInstanceResponse: + ListTicketMetadataResponse: example: data: - - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z - tenantId: DE + - tenantId: DE customerId: "54321" - - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z - tenantId: DE + name: type + availableChoices: '["Choice 1", "Choice 2"]' + - tenantId: DE customerId: "54321" + name: type + availableChoices: '["Choice 1", "Choice 2"]' _links: - self: /v1/compute/instances/12345 + self: v1/tickets/metadata properties: data: items: - $ref: '#/components/schemas/ReinstallInstanceResponseData' + $ref: '#/components/schemas/MetadataType' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345 + self: v1/tickets/metadata required: - _links - data type: object - ExtraStorageRequest: - properties: - ssd: - description: Specify the size in TB and the quantity - items: - type: string - type: array - nvme: - description: Specify the size in TB and the quantity - items: - type: string - type: array - type: object - AddOnRequest: - properties: - id: - description: Id of the Addon. Please refer to list [here](https://contabo.com/en/product-list/?show_ids=true). - example: 1019 - format: int64 - type: integer - quantity: - description: The number of Addons you wish to aquire. - example: 4 - format: int64 - type: integer - required: - - id - - quantity - type: object - CreateInstanceAddons: - properties: - privateNetworking: - description: Set this attribute if you want to upgrade your instance with - the Private Networking addon. Please provide an empty object for the - time being as value. There will be more configuration possible in the - future. - example: {} - type: object - additionalIps: - description: Set this attribute if you want to upgrade your instance with - the Additional IPs addon. Please provide an empty object for the time - being as value. There will be more configuration possible in the future. - example: {} - type: object - extraStorage: - allOf: - - $ref: '#/components/schemas/ExtraStorageRequest' - description: Set this attribute if you want to upgrade your instance with - the Extra Storage addon. - example: {} - customImage: - description: Set this attribute if you want to upgrade your instance with - the Custom Images addon. Please provide an empty object for the time - being as value. There will be more configuration possible in the future. - example: {} - type: object - addonsIds: - items: - $ref: '#/components/schemas/AddOnRequest' - type: array - type: object - CreateInstanceRequest: + TagResponse1: example: - license: PleskHost - period: 6 - imageId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - userData: |- - #cloud-config - user: admin - timezone: Europe/Berlin - chpasswd: - expire: False - productId: V45 - displayName: VPS - addOns: - privateNetworking: {} - additionalIps: {} - extraStorage: {} - customImage: {} - defaultUser: root - sshKeys: '[123, 125]' - region: EU - applicationId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - rootPassword: 1 + color: '#0A78C3' + tagId: 12345 + tenantId: DE + customerId: "54321" + name: Web-Server properties: - imageId: - default: afecbb85-e2fc-46f0-9684-b46b1faf00bb - description: ImageId to be used to setup the compute instance. Default is - Ubuntu 22.04 - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - type: string - productId: - default: V45 - description: Default is V45 - example: V45 + tenantId: + description: Your customer tenant id + example: DE minLength: 1 type: string - region: - default: EU - description: Instance Region where the compute instance should be located. - Default is EU - enum: - - EU - - US-central - - US-east - - US-west - - SIN - - UK - - AUS - - JPN - example: EU + customerId: + description: Your customer number + example: "54321" minLength: 1 type: string - sshKeys: - description: Array of `secretId`s of public SSH keys for logging into as - `defaultUser` with administrator/root privileges. Applies to Linux/BSD - systems. Please refer to Secrets Management API. - example: '[123, 125]' - items: - format: int64 - type: integer - type: array - rootPassword: - description: '`secretId` of the password for the `defaultUser` with administrator/root - privileges. For Linux/BSD please use SSH, for Windows RDP. Please refer - to Secrets Management API.' - example: 1 - format: int64 - type: integer - userData: - description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize - during start of compute instance.' - example: |- - #cloud-config - user: admin - timezone: Europe/Berlin - chpasswd: - expire: False - type: string - license: - description: Additional licence in order to enhance your chosen product, - mainly needed for software licenses on your product (not needed for windows). - enum: - - cPanel5 - - cPanel30 - - cPanel50 - - cPanel100 - - cPanel150 - - cPanel200 - - cPanel250 - - cPanel300 - - cPanel350 - - cPanel400 - - cPanel450 - - cPanel500 - - cPanel550 - - cPanel600 - - cPanel650 - - cPanel700 - - cPanel750 - - cPanel800 - - cPanel850 - - cPanel900 - - cPanel950 - - cPanel1000 - - PleskAdmin - - PleskHost - - PleskPro - example: PleskHost - type: string - period: - default: 1 - description: 'Initial contract period in months. Available periods are: - 1, 3, 6 and 12 months. Default to 1 month' - example: 6 - format: int64 - type: integer - displayName: - description: The display name of the instance - example: VPS + tagId: + description: Tag's id + example: 12345 + type: number + name: + description: Tag's name + example: Web-Server maxLength: 255 + minLength: 1 type: string - defaultUser: - default: admin - description: Default user name created for login during (re-)installation - with administrative privileges. Allowed values for Linux/BSD are `admin` - (use sudo to apply administrative privileges like root) or `root`. Allowed - values for Windows are `admin` (has administrative privileges like administrator) - or `administrator`. - enum: - - root - - admin - - administrator - example: root + color: + description: Tag's color + example: '#0A78C3' + maxLength: 7 + minLength: 4 type: string - addOns: + required: + - color + - customerId + - name + - tagId + - tenantId + type: object + ListTagResponse: + example: + data: + - color: '#0A78C3' + tagId: 12345 + tenantId: DE + customerId: "54321" + name: Web-Server + - color: '#0A78C3' + tagId: 12345 + tenantId: DE + customerId: "54321" + name: Web-Server + _links: + first: /v1/tags?page=1 + previous: /v1/tags?page=19 + self: /v1/tags/12345 + next: /v1/tags?page=21 + last: /v1/tags?page=101 + _pagination: "" + properties: + _pagination: allOf: - - $ref: '#/components/schemas/CreateInstanceAddons' - description: Set attributes in the addons object for the corresponding ones - that need to be added to the instance + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. + data: + items: + $ref: '#/components/schemas/TagResponse1' + type: array + _links: + allOf: + - $ref: '#/components/schemas/Links' example: - privateNetworking: {} - additionalIps: {} - extraStorage: {} - customImage: {} - applicationId: - description: Application ID - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 + first: /v1/tags?page=1 + previous: /v1/tags?page=19 + self: /v1/tags/12345 + next: /v1/tags?page=21 + last: /v1/tags?page=101 + required: + - _links + - _pagination + - data + type: object + CreateTagRequest: + example: + color: '#0A78C3' + name: Web-Server + properties: + name: + description: The name of the tag. Tags may contain letters, numbers, colons, + dashes, and underscores. There is a limit of 255 characters per tag. + example: Web-Server + maxLength: 255 + minLength: 1 + type: string + color: + default: '#0A78C3' + description: 'The color of the tag. Color can be specified using hexadecimal + value. Default color is #0A78C3' + example: '#0A78C3' + maxLength: 7 + minLength: 4 type: string required: - - period + - color + - name type: object - CreateInstanceResponseData: + CreateTagResponseData: example: - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V45 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 + tagId: 12345 tenantId: DE customerId: "54321" - osType: Linux - sshKeys: - - 123 - - 125 - region: EU properties: tenantId: description: Your customer tenant id @@ -13986,119 +13575,112 @@ components: example: "54321" minLength: 1 type: string - instanceId: - description: Instance's id + tagId: + description: Tag's id example: 12345 - format: int64 - type: integer - createdDate: - description: Creation date for instance - example: 2021-06-02T12:32:03.363Z - format: date-time - type: string - imageId: - description: Image's id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - type: string - productId: - description: Product ID - example: V45 - type: string - region: - description: Instance Region where the compute instance should be located. - example: EU - type: string - addOns: + type: number + required: + - customerId + - tagId + - tenantId + type: object + CreateTagResponse: + example: + data: + - tagId: 12345 + tenantId: DE + customerId: "54321" + - tagId: 12345 + tenantId: DE + customerId: "54321" + _links: + self: /v1/tags/12345 + properties: + data: items: - $ref: '#/components/schemas/AddOnResponse' + $ref: '#/components/schemas/CreateTagResponseData' type: array - osType: - description: Type of operating system (OS) - example: Linux - type: string - status: - $ref: '#/components/schemas/instanceStatus' - sshKeys: - description: Array of `secretId`s of public SSH keys for logging into as - `defaultUser` with administrator/root privileges. Applies to Linux/BSD - systems. Please refer to Secrets Management API. + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' example: - - 123 - - 125 - items: - format: int64 - type: integer - type: array + self: /v1/tags/12345 required: - - addOns - - createdDate - - customerId - - imageId - - instanceId - - osType - - productId - - region - - sshKeys - - status - - tenantId + - _links + - data type: object - CreateInstanceResponse: + FindTagResponse: example: data: - - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V45 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 + - color: '#0A78C3' + tagId: 12345 tenantId: DE customerId: "54321" - osType: Linux - sshKeys: - - 123 - - 125 - region: EU - - instanceId: 12345 - createdDate: 2021-06-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - productId: V45 - addOns: - - quantity: 4 - id: 1431 - - quantity: 4 - id: 1431 + name: Web-Server + - color: '#0A78C3' + tagId: 12345 tenantId: DE customerId: "54321" - osType: Linux - sshKeys: - - 123 - - 125 - region: EU + name: Web-Server _links: - self: /v1/compute/instances/12345 + self: /v1/tags/12345 properties: data: items: - $ref: '#/components/schemas/CreateInstanceResponseData' + $ref: '#/components/schemas/TagResponse1' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345 + self: /v1/tags/12345 required: - _links - data type: object - CancelInstanceResponseData: + UpdateTagRequest: example: - cancelDate: 2021-06-03T00:00:00.000+0000 - instanceId: 12345 + color: '#0A78C3' + name: Updated-Web-Server + properties: + name: + description: The name of the tag. Tags may contain letters, numbers, colons, + dashes, and underscores. There is a limit of 255 characters per tag. + example: Updated-Web-Server + maxLength: 255 + minLength: 1 + type: string + color: + description: 'The color of the tag. Color can be specified using hexadecimal + value. Default color is #0A78C3' + example: '#0A78C3' + maxLength: 7 + minLength: 4 + type: string + type: object + UpdateTagResponse: + example: + _links: + self: /v1/tags/12345 + properties: + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + description: Links for easy navigation. + example: + self: /v1/tags/12345 + required: + - _links + type: object + AssignmentResponse: + example: + resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + tagId: 12345 tenantId: DE customerId: "54321" + resourceName: Instance + tagName: Web-Server + resourceType: instance properties: tenantId: description: Your customer tenant id @@ -14110,89 +13692,163 @@ components: example: "54321" minLength: 1 type: string - instanceId: - description: Instance's id + tagId: + description: Tag's id example: 12345 - format: int64 - type: integer - cancelDate: - description: The date on which the instance will be cancelled - example: 2021-06-03 - format: date + type: number + tagName: + description: Tag's name + example: Web-Server + maxLength: 255 + minLength: 1 + type: string + resourceType: + description: Resource type. Resource type is one of `instance|image|object-storage`. + example: instance + minLength: 1 + type: string + resourceId: + description: Resource id + example: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + minLength: 1 + type: string + resourceName: + description: Resource name + example: Instance + minLength: 1 type: string required: - - cancelDate - customerId - - instanceId + - resourceId + - resourceName + - resourceType + - tagId + - tagName - tenantId type: object - CancelInstanceResponse: + ListAssignmentResponse: example: data: - - cancelDate: 2021-06-03T00:00:00.000+0000 - instanceId: 12345 + - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + tagId: 12345 tenantId: DE customerId: "54321" - - cancelDate: 2021-06-03T00:00:00.000+0000 - instanceId: 12345 + resourceName: Instance + tagName: Web-Server + resourceType: instance + - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + tagId: 12345 tenantId: DE customerId: "54321" + resourceName: Instance + tagName: Web-Server + resourceType: instance _links: - self: /v1/compute/instances/12345 + first: /v1/tags/12345/assignments?page=1 + previous: /v1/tags/12345/assignments?page=19 + self: /v1/tags/12345/assignments/instance/23456 + next: /v1/tags/12345/assignments?page=21 + last: /v1/tags/12345/assignments?page=101 + _pagination: "" properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/CancelInstanceResponseData' + $ref: '#/components/schemas/AssignmentResponse' type: array _links: allOf: - - $ref: '#/components/schemas/SelfLinks' + - $ref: '#/components/schemas/Links' example: - self: /v1/compute/instances/12345 + first: /v1/tags/12345/assignments?page=1 + previous: /v1/tags/12345/assignments?page=19 + self: /v1/tags/12345/assignments/instance/23456 + next: /v1/tags/12345/assignments?page=21 + last: /v1/tags/12345/assignments?page=101 required: - _links + - _pagination - data type: object - FirewallingUpgradeRequest: + TagAssignmentSelfLinks: properties: - assignFirewalls: - description: List of IDs of firewalls the upgraded instance should be assigned - to immediately. If the list is empty or this property is not provided - the instance will be assigned to your current default firewall. - items: - type: string - type: array - type: object - PrivateNetworkingUpgradeRequest: - properties: {} + self: + description: Link to current resource. + type: string + tag: + description: Link to related tag. + type: string + _resource: + description: Link to assigned resource + type: string + required: + - _resource + - self + - tag type: object - AddOnQuantityRequest: - properties: - quantity: - description: The number of Addons you wish to aquire. - example: 4 - format: int64 - type: integer + FindAssignmentResponse: + example: + data: + - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + tagId: 12345 + tenantId: DE + customerId: "54321" + resourceName: Instance + tagName: Web-Server + resourceType: instance + - resourceId: d65ecf3b-30db-4dc2-9e88-dfc21a14a6bc + tagId: 12345 + tenantId: DE + customerId: "54321" + resourceName: Instance + tagName: Web-Server + resourceType: instance + _links: + self: /v1/tags/12345/assignments/instance/23456 + tag: /v1/tags/12345 + instance: /v1/compute/instances/23456 + properties: + data: + items: + $ref: '#/components/schemas/AssignmentResponse' + type: array + _links: + allOf: + - $ref: '#/components/schemas/TagAssignmentSelfLinks' + example: + self: /v1/tags/12345/assignments/instance/23456 + tag: /v1/tags/12345 + instance: /v1/compute/instances/23456 required: - - quantity + - _links + - data type: object - UpgradeInstanceRequest: + CreateAssignmentResponse: example: - privateNetworking: {} + _links: + self: /v1/tags/12345/assignments/instance/6549 + tag: /v1/tags/12345 + instance: /v1/compute/instance/6549 properties: - privateNetworking: + _links: allOf: - - $ref: '#/components/schemas/PrivateNetworkingUpgradeRequest' - description: Set this attribute if you want to upgrade your instance with - the Private Networking addon. Please provide an empty object for the time - being as value. There will be more configuration possible in the future. - example: {} + - $ref: '#/components/schemas/TagAssignmentSelfLinks' + description: Links for easy navigation. + example: + self: /v1/tags/12345/assignments/instance/6549 + tag: /v1/tags/12345 + instance: /v1/compute/instance/6549 + required: + - _links type: object - InstancesActionsAuditResponse: + TagAuditResponse: example: traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + tagId: 12345 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" @@ -14204,19 +13860,33 @@ components: action: CREATED id: 12345 timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + username: John Doe properties: + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string id: - description: The ID of the audit entry. + description: The identifier of the audit entry. example: 12345 - format: int64 - type: integer + type: number + tagId: + description: The identifier of the audit entry. + example: 12345 + minimum: 0 + type: number action: description: Type of the action. enum: - CREATED - - UPDATED - DELETED + - UPDATED example: CREATED type: string timestamp: @@ -14224,24 +13894,14 @@ components: example: 2021-03-30T11:35:06.177Z format: date-time type: string - tenantId: - description: Customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Customer ID - example: "54321" - minLength: 1 - type: string changedBy: - description: Id of user who performed the change - example: c4c800ff-e524-47dd-9543-71dfc8b91113 + description: User ID + example: "54321" minLength: 1 type: string username: description: Name of the user which led to the change. - example: John.Doe + example: John Doe type: string requestId: description: The requestId of the API call which led to the change. @@ -14251,12 +13911,6 @@ components: description: The traceId of the API call which led to the change. example: 78E9A428-94E9-4A2A-92F5-26038C6884F type: string - instanceId: - description: The identifier of the instancesActions - example: 12345 - format: int64 - minimum: 0 - type: integer changes: description: List of actual changes. example: @@ -14270,19 +13924,19 @@ components: - changedBy - customerId - id - - instanceId - requestId + - tagId - tenantId - timestamp - traceId - username type: object - ListInstancesActionsAuditResponse: + ListTagAuditsResponse: example: data: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + tagId: 12345 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" @@ -14294,10 +13948,10 @@ components: action: CREATED id: 12345 timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + username: John Doe - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + tagId: 12345 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" @@ -14309,13 +13963,160 @@ components: action: CREATED id: 12345 timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + username: John Doe _links: - first: /v1/compute/instances/actions/audits?page=2 - previous: /v1/compute/instances/actions/audits?page=2 - next: /v1/compute/instances/actions/audits?page=3 - last: /v1/compute/instances/actions/audits?page=10 - self: /v1/compute/instances/actions/audits + first: /v1/tags/audits?page=1 + previous: /v1/tags/audits?page=19 + self: /v1/tags/audits?page=20 + next: /v1/tags/audits?page=21 + last: /v1/tags/audits?page=101 + _pagination: "" + properties: + _pagination: + allOf: + - $ref: '#/components/schemas/PaginationMeta' + description: Data about pagination like how many results, pages, page size. + data: + items: + $ref: '#/components/schemas/TagAuditResponse' + type: array + _links: + allOf: + - $ref: '#/components/schemas/Links' + example: + first: /v1/tags/audits?page=1 + previous: /v1/tags/audits?page=19 + self: /v1/tags/audits?page=20 + next: /v1/tags/audits?page=21 + last: /v1/tags/audits?page=101 + required: + - _links + - _pagination + - data + type: object + AssignmentAuditResponse: + example: + traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F5 + resourceId: a1b2c3 + tagId: 12345 + changes: '{}' + changedBy: "54321" + requestId: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 + tenantId: DE + customerId: "54321" + action: CREATED | DELETED + id: 12345 + resourceType: instance + timestamp: 2000-01-23T04:56:07.000+00:00 + username: John Doe + properties: + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + id: + description: The identifier of the audit entry. + example: 12345 + type: number + resourceId: + description: Resource's id + example: a1b2c3 + type: string + resourceType: + description: Resource type. Resource type is one of `instance|image|object-storage`. + example: instance + type: string + tagId: + description: Tag's id + example: 12345 + minimum: 0 + type: number + action: + description: Audit Action + enum: + - CREATED + - DELETED + example: CREATED | DELETED + type: string + timestamp: + description: Audit creation date + format: date-time + type: string + changedBy: + description: User ID + example: "54321" + minLength: 1 + type: string + username: + description: User Full Name + example: John Doe + type: string + requestId: + description: Request ID + example: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 + type: string + traceId: + description: Trace ID + example: 78E9A428-94E9-4A2A-92F5-26038C6884F5 + type: string + changes: + description: Changes made for a specific Tag + type: object + required: + - action + - changedBy + - customerId + - id + - requestId + - resourceId + - resourceType + - tagId + - tenantId + - timestamp + - traceId + - username + type: object + ListAssignmentAuditsResponse: + example: + data: + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F5 + resourceId: a1b2c3 + tagId: 12345 + changes: '{}' + changedBy: "54321" + requestId: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 + tenantId: DE + customerId: "54321" + action: CREATED | DELETED + id: 12345 + resourceType: instance + timestamp: 2000-01-23T04:56:07.000+00:00 + username: John Doe + - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F5 + resourceId: a1b2c3 + tagId: 12345 + changes: '{}' + changedBy: "54321" + requestId: 04E0F898-37B4-48BC-A794-1A57ABE6AA31 + tenantId: DE + customerId: "54321" + action: CREATED | DELETED + id: 12345 + resourceType: instance + timestamp: 2000-01-23T04:56:07.000+00:00 + username: John Doe + _links: + first: /v1/tags/assignments/audits?page=1 + previous: /v1/tags/assignments/audits?page=19 + self: /v1/tags/assignments/audits?page=20 + next: /v1/tags/assignments/audits?page=21 + last: /v1/tags/assignments/audits?page=101 _pagination: "" properties: _pagination: @@ -14324,150 +14125,445 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/InstancesActionsAuditResponse' + $ref: '#/components/schemas/AssignmentAuditResponse' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/compute/instances/actions/audits?page=2 - previous: /v1/compute/instances/actions/audits?page=2 - next: /v1/compute/instances/actions/audits?page=3 - last: /v1/compute/instances/actions/audits?page=10 - self: /v1/compute/instances/actions/audits + first: /v1/tags/assignments/audits?page=1 + previous: /v1/tags/assignments/audits?page=19 + self: /v1/tags/assignments/audits?page=20 + next: /v1/tags/assignments/audits?page=21 + last: /v1/tags/assignments/audits?page=101 required: - _links - _pagination - data type: object - InstancesAuditResponse: + ResourcePermissionsResponse: example: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + tagId: 12345 + tagName: Web + properties: + tagId: + description: Tag's id + example: 12345 + format: int64 + type: integer + tagName: + description: Tag name. The resriction is based on the resources which have + been assigned to that tag. If no resource has been assigned to the given + tag, no access will be possible. + example: Web + type: string + required: + - tagId + - tagName + type: object + PermissionResponse: + example: + apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + properties: + apiName: + description: API endpoint. In order to get a list availbale api enpoints + please refer to the GET api-permissions endpoint. + example: /v1/compute/instances + type: string + actions: + description: Action allowed for the API endpoint. Basically `CREATE` corresponds + to POST endpoints, `READ` to GET endpoints, `UPDATE` to PATCH / PUT endpoints + and `DELETE` to DELETE endpoints. + example: + - CREATE + - READ + items: + enum: + - CREATE + - READ + - UPDATE + - DELETE + type: string + type: array + resources: + items: + $ref: '#/components/schemas/ResourcePermissionsResponse' + type: array + required: + - actions + - apiName + type: object + RoleResponse: + example: + roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + name: infrastructure + admin: true + type: custom properties: - id: - description: The ID of the audit entry. + roleId: + description: Role's id example: 12345 format: int64 type: integer - action: - description: Type of the action. - enum: - - CREATED - - UPDATED - - DELETED - example: CREATED + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 type: string - timestamp: - description: When the change took place. - example: 2021-03-30T11:35:06.177Z - format: date-time + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + name: + description: Role's name + example: infrastructure + type: string + admin: + description: Admin + example: true + type: boolean + accessAllResources: + description: Access All Resources + example: true + type: boolean + type: + description: Role type can be either `default` or `custom`. The `default` + roles cannot be modified or deleted. + example: custom type: string + permissions: + items: + $ref: '#/components/schemas/PermissionResponse' + type: array + required: + - accessAllResources + - admin + - customerId + - name + - roleId + - tenantId + - type + type: object + UserResponse: + example: + owner: false + firstName: John + lastName: Doe + emailVerified: false + totp: false + roles: + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + tenantId: DE + customerId: "54321" + locale: de + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + email: john.doe@example.com + enabled: false + properties: tenantId: - description: Customer tenant id + description: Your customer tenant id example: DE minLength: 1 type: string - customerId: - description: Customer ID - example: "54321" + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + userId: + description: The identifier of the user. + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + type: string + firstName: + description: The first name of the user. Users may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + user. + example: John + maxLength: 255 + minLength: 1 + type: string + lastName: + description: The last name of the user. Users may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + user. + example: Doe + maxLength: 255 minLength: 1 type: string - changedBy: - description: Id of user who performed the change - example: c4c800ff-e524-47dd-9543-71dfc8b91113 + email: + description: The email of the user to which activation and forgot password + links are being sent to. There is a limit of 255 characters per email. + example: john.doe@example.com + maxLength: 255 minLength: 1 type: string - username: - description: Name of the user which led to the change. - example: John.Doe - type: string - requestId: - description: The requestId of the API call which led to the change. - example: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 - type: string - traceId: - description: The traceId of the API call which led to the change. - example: 78E9A428-94E9-4A2A-92F5-26038C6884F + emailVerified: + description: User email verification status. + example: false + type: boolean + enabled: + description: If uses is not enabled, he can't login and thus use services + any longer. + example: false + type: boolean + totp: + description: Enable or disable two-factor authentication (2FA) via time + based OTP. + example: false + type: boolean + locale: + description: The locale of the user. This can be `de-DE`, `de`, `en-US`, + `en` + enum: + - de-DE + - de + - en-US + - en + example: de type: string - instanceId: - description: The identifier of the instance - example: 12345 - format: int64 - minimum: 0 - type: integer - changes: - description: List of actual changes. - example: - prev: - name: test - new: - name: test1 - type: object + roles: + description: The roles as list of `roleId`s of the user. + items: + $ref: '#/components/schemas/RoleResponse' + type: array + owner: + description: If user is owner he will have permissions to all API endpoints + and resources. Enabling this will superseed all role definitions and `accessAllResources`. + example: false + type: boolean required: - - action - - changedBy - customerId - - id - - instanceId - - requestId + - email + - emailVerified + - enabled + - firstName + - lastName + - locale + - owner + - roles - tenantId - - timestamp - - traceId - - username + - totp + - userId type: object - ListInstancesAuditResponse: + ListUserResponse: example: data: - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + - owner: false + firstName: John + lastName: Doe + emailVerified: false + totp: false + roles: + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe - - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 - requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + locale: de + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + email: john.doe@example.com + enabled: false + - owner: false + firstName: John + lastName: Doe + emailVerified: false + totp: false + roles: + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom tenantId: DE customerId: "54321" - changes: - prev: - name: test - new: - name: test1 - action: CREATED - id: 12345 - timestamp: 2021-03-30T11:35:06.177Z - username: John.Doe + locale: de + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + email: john.doe@example.com + enabled: false _links: - first: /v1/compute/instances/audits?page=2 - previous: /v1/compute/instances/audits?page=2 - next: /v1/compute/instances/audits?page=3 - last: /v1/compute/instances/audits?page=10 - self: /v1/compute/instances/audits + first: /v1/users?page=1 + next: /v1/users?page=19 + self: /v1/users/12345 + previous: /v1/users?page=21 + last: /v1/users?page=101 _pagination: "" properties: _pagination: @@ -14476,528 +14572,445 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/InstancesAuditResponse' + $ref: '#/components/schemas/UserResponse' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/compute/instances/audits?page=2 - previous: /v1/compute/instances/audits?page=2 - next: /v1/compute/instances/audits?page=3 - last: /v1/compute/instances/audits?page=10 - self: /v1/compute/instances/audits + first: /v1/users?page=1 + next: /v1/users?page=19 + self: /v1/users/12345 + previous: /v1/users?page=21 + last: /v1/users?page=101 required: - _links - _pagination - data type: object - TagResponse1: + CreateUserRequest: example: - tagId: 12345 - tagName: Web-Server + firstName: John + lastName: Doe + totp: false + roles: + - 1 + - 2 + - 3 + - 4 + locale: de + email: john.doe@example.com + enabled: false properties: - tagId: - description: Tag's id - example: 12345 - type: number - tagName: - description: Tag's name - example: Web-Server + firstName: + description: The name of the user. Names may contain letters, numbers, colons, + dashes, and underscores. There is a limit of 255 characters per user. + example: John + maxLength: 255 + minLength: 1 + type: string + lastName: + description: The last name of the user. Users may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + user. + example: Doe maxLength: 255 minLength: 1 type: string + email: + description: The email of the user to which activation and forgot password + links are being sent to. There is a limit of 255 characters per email. + example: john.doe@example.com + maxLength: 255 + minLength: 1 + type: string + enabled: + description: If user is not enabled, he can't login and thus use services + any longer. + example: false + type: boolean + totp: + description: Enable or disable two-factor authentication (2FA) via time + based OTP. + example: false + type: boolean + locale: + description: The locale of the user. This can be `de-DE`, `de`, `en-US`, + `en` + enum: + - de-DE + - de + - en-US + - en + example: de + type: string + roles: + description: The roles as list of `roleId`s of the user. + example: + - 1 + - 2 + - 3 + - 4 + items: + format: int64 + type: integer + type: array required: - - tagId - - tagName + - email + - enabled + - locale + - totp type: object - ListImageResponseData: + CreateUserResponseData: example: - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - lastModifiedDate: 2021-06-04T06:27:12Z - format: iso - errorMessage: Error downloading image from provided URL - description: Ubuntu Server 20.04.2 LTS - sizeMb: 1024 - creationDate: 2021-06-03T06:27:12Z - version: 20.04.2 - url: https://example.com/image.qcow2 - tags: - - tagId: 12345 - tagName: Web-Server - - tagId: 12345 - tagName: Web-Server - uploadedSizeMb: 1024 tenantId: DE - customerId: "12345" - name: Custom Image Ubuntu - osType: Linux - status: Pending - standardImage: true + customerId: "54321" + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 properties: - imageId: - description: Image's id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - type: string tenantId: description: Your customer tenant id - enum: - - DE - - INT example: DE minLength: 1 type: string customerId: - description: Customer ID - example: "12345" + description: Your customer number + example: "54321" minLength: 1 type: string - name: - description: Image Name - example: Custom Image Ubuntu - type: string - description: - description: Image Description - example: Ubuntu Server 20.04.2 LTS - type: string - url: - description: URL from where the image has been downloaded / provided. - example: https://example.com/image.qcow2 - type: string - sizeMb: - description: Image Size in MB - example: 1024 - type: number - uploadedSizeMb: - description: Image Uploaded Size in MB - example: 1024 - type: number - osType: - description: Type of operating system (OS) - example: Linux - type: string - version: - description: Version number to distinguish the contents of an image. Could - be the version of the operating system for example. - example: 20.04.2 - type: string - format: - description: Image format - enum: - - iso - - qcow2 - example: iso - type: string - status: - description: Image status (e.g. if image is still downloading) - example: Pending - type: string - errorMessage: - description: Image download error message - example: Error downloading image from provided URL - type: string - standardImage: - description: Flag indicating that image is either a standard (true) or a - custom image (false) - example: true - type: boolean - creationDate: - description: The creation date time for the image - example: 2021-06-03T06:27:12Z - format: date-time - type: string - lastModifiedDate: - description: The last modified date time for the image - example: 2021-06-04T06:27:12Z - format: date-time + userId: + description: User's id + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 type: string - tags: - description: The tags assigned to the image - items: - $ref: '#/components/schemas/TagResponse1' - type: array required: - - creationDate - - customerId - - description - - errorMessage - - format - - imageId - - lastModifiedDate - - name - - osType - - sizeMb - - standardImage - - status - - tags - - tenantId - - uploadedSizeMb - - url - - version - type: object - ListImageResponse: - example: - data: - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - lastModifiedDate: 2021-06-04T06:27:12Z - format: iso - errorMessage: Error downloading image from provided URL - description: Ubuntu Server 20.04.2 LTS - sizeMb: 1024 - creationDate: 2021-06-03T06:27:12Z - version: 20.04.2 - url: https://example.com/image.qcow2 - tags: - - tagId: 12345 - tagName: Web-Server - - tagId: 12345 - tagName: Web-Server - uploadedSizeMb: 1024 - tenantId: DE - customerId: "12345" - name: Custom Image Ubuntu - osType: Linux - status: Pending - standardImage: true - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - lastModifiedDate: 2021-06-04T06:27:12Z - format: iso - errorMessage: Error downloading image from provided URL - description: Ubuntu Server 20.04.2 LTS - sizeMb: 1024 - creationDate: 2021-06-03T06:27:12Z - version: 20.04.2 - url: https://example.com/image.qcow2 - tags: - - tagId: 12345 - tagName: Web-Server - - tagId: 12345 - tagName: Web-Server - uploadedSizeMb: 1024 - tenantId: DE - customerId: "12345" - name: Custom Image Ubuntu - osType: Linux - status: Pending - standardImage: true + - customerId + - tenantId + - userId + type: object + CreateUserResponse: + example: + data: + - tenantId: DE + customerId: "54321" + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + - tenantId: DE + customerId: "54321" + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 _links: - first: /v1/compute/images?page=1 - previous: /v1/compute/images?page=19 - self: /v1/compute/images?page=20 - next: /v1/compute/images?page=21 - last: /v1/compute/images?page=101 - _pagination: "" + self: /v1/users/12345 properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/ListImageResponseData' + $ref: '#/components/schemas/CreateUserResponseData' type: array _links: allOf: - - $ref: '#/components/schemas/Links' + - $ref: '#/components/schemas/SelfLinks' example: - first: /v1/compute/images?page=1 - previous: /v1/compute/images?page=19 - self: /v1/compute/images?page=20 - next: /v1/compute/images?page=21 - last: /v1/compute/images?page=101 + self: /v1/users/12345 required: - _links - - _pagination - data type: object - CreateCustomImageRequest: + FindUserResponse: example: - name: Ubuntu Custom Image - osType: Linux - description: Ubuntu Server 20.04.2 LTS - version: 20.04.2 - url: https://example.com/image.qcow2 + data: + - owner: false + firstName: John + lastName: Doe + emailVerified: false + totp: false + roles: + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + tenantId: DE + customerId: "54321" + locale: de + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + email: john.doe@example.com + enabled: false + - owner: false + firstName: John + lastName: Doe + emailVerified: false + totp: false + roles: + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true + tenantId: DE + customerId: "54321" + name: infrastructure + admin: true + type: custom + tenantId: DE + customerId: "54321" + locale: de + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + email: john.doe@example.com + enabled: false + _links: + self: /v1/users/12345 properties: - name: - description: Image Name - example: Ubuntu Custom Image - type: string - description: - description: Image Description - example: Ubuntu Server 20.04.2 LTS - type: string - url: - description: URL from where the image has been downloaded / provided. - example: https://example.com/image.qcow2 - type: string - osType: - description: Provided type of operating system (OS). Please specify `Windows` - for MS Windows and `Linux` for other OS. Specifying wrong OS type may - lead to disfunctional cloud instance. - enum: - - Windows - - Linux - example: Linux - type: string - version: - description: Version number to distinguish the contents of an image. Could - be the version of the operating system for example. - example: 20.04.2 - type: string + data: + items: + $ref: '#/components/schemas/UserResponse' + type: array + _links: + allOf: + - $ref: '#/components/schemas/SelfLinks' + example: + self: /v1/users/12345 required: - - name - - osType - - url - - version + - _links + - data type: object - CreateCustomImageResponseData: + UpdateUserRequest: example: - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - tenantId: DE - customerId: "54321" + firstName: John + lastName: Doe + totp: false + roles: + - 1 + - 2 + - 3 + - 4 + locale: de + email: john.doe@example.com + enabled: false properties: - tenantId: - description: Your customer tenant id - example: DE + firstName: + description: The name of the user. Names may contain letters, numbers, colons, + dashes, and underscores. There is a limit of 255 characters per user. + example: John + maxLength: 255 minLength: 1 type: string - customerId: - description: Your customer number - example: "54321" + lastName: + description: The last name of the user. Users may contain letters, numbers, + colons, dashes, and underscores. There is a limit of 255 characters per + user. + example: Doe + maxLength: 255 minLength: 1 type: string - imageId: - description: Image's id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + email: + description: The email of the user to which activation and forgot password + links are being sent to. There is a limit of 255 characters per email. + example: john.doe@example.com + maxLength: 255 + minLength: 1 type: string - required: - - customerId - - imageId - - tenantId + enabled: + description: If user is not enabled, he can't login and thus use services + any longer. + example: false + type: boolean + totp: + description: Enable or disable two-factor authentication (2FA) via time + based OTP. + example: false + type: boolean + locale: + description: The locale of the user. This can be `de-DE`, `de`, `en-US`, + `en` + enum: + - de-DE + - de + - en-US + - en + example: de + type: string + roles: + description: The roles as list of `roleId`s of the user. + example: + - 1 + - 2 + - 3 + - 4 + items: + format: int64 + type: integer + type: array type: object - CreateCustomImageResponse: + UpdateUserResponse: example: - data: - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - tenantId: DE - customerId: "54321" - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - tenantId: DE - customerId: "54321" _links: - self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + self: /v1/users/12345 properties: - data: - items: - $ref: '#/components/schemas/CreateCustomImageResponseData' - type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' + description: Links for easy navigation. example: - self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + self: /v1/users/12345 required: - _links - - data - type: object - CreateCustomImageFailResponse: - properties: - message: - description: 'Unsupported Media Type: Please provide a direct link to an - .iso or .qcow2 image.' - example: Unsupported Media Type - type: string - statusCode: - description: statuscode:415 - example: 415 - type: integer - required: - - message - - statusCode type: object - ImageResponse: + ClientResponse: example: - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - lastModifiedDate: 2021-06-04T06:27:12Z - format: iso - errorMessage: Error downloading image from provided URL - description: Ubuntu Server 20.04.2 LTS - sizeMb: 1024 - creationDate: 2021-06-03T06:27:12Z - version: 20.04.2 - url: https://example.com/image.qcow2 - uploadedSizeMb: 1024 + clientId: DE-54321 tenantId: DE - customerId: "12345" - name: Custom Image Ubuntu - osType: Linux - status: Pending - standardImage: true + customerId: "54321" + id: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + secret: 7271e905-239e-4d15-a8c5-527743a58390 properties: - imageId: - description: Image's id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - type: string tenantId: description: Your customer tenant id - enum: - - DE - - INT example: DE minLength: 1 type: string customerId: - description: Customer ID - example: "12345" + description: Your customer number + example: "54321" minLength: 1 type: string - name: - description: Image Name - example: Custom Image Ubuntu - type: string - description: - description: Image Description - example: Ubuntu Server 20.04.2 LTS - type: string - url: - description: URL from where the image has been downloaded / provided. - example: https://example.com/image.qcow2 - type: string - sizeMb: - description: Image Size in MB - example: 1024 - type: number - uploadedSizeMb: - description: Image Uploaded Size in MB - example: 1024 - type: number - osType: - description: Type of operating system (OS) - example: Linux - type: string - version: - description: Version number to distinguish the contents of an image. Could - be the version of the operating system for example. - example: 20.04.2 - type: string - format: - description: Image format - enum: - - iso - - qcow2 - example: iso - type: string - status: - description: Image status (e.g. if image is still downloading) - example: Pending - type: string - errorMessage: - description: Image download error message - example: Error downloading image from provided URL + id: + description: Client's id + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 type: string - standardImage: - description: Flag indicating that image is either a standard (true) or a - custom image (false) - example: true - type: boolean - creationDate: - description: The creation date time for the image - example: 2021-06-03T06:27:12Z - format: date-time + clientId: + description: IDM client id + example: DE-54321 type: string - lastModifiedDate: - description: The last modified date time for the image - example: 2021-06-04T06:27:12Z - format: date-time + secret: + description: IDM client secret + example: 7271e905-239e-4d15-a8c5-527743a58390 type: string required: - - creationDate + - clientId - customerId - - description - - errorMessage - - format - - imageId - - lastModifiedDate - - name - - osType - - sizeMb - - standardImage - - status + - id + - secret - tenantId - - uploadedSizeMb - - url - - version type: object - FindImageResponse: + FindClientResponse: example: data: - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - lastModifiedDate: 2021-06-04T06:27:12Z - format: iso - errorMessage: Error downloading image from provided URL - description: Ubuntu Server 20.04.2 LTS - sizeMb: 1024 - creationDate: 2021-06-03T06:27:12Z - version: 20.04.2 - url: https://example.com/image.qcow2 - uploadedSizeMb: 1024 + - clientId: DE-54321 tenantId: DE - customerId: "12345" - name: Custom Image Ubuntu - osType: Linux - status: Pending - standardImage: true - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - lastModifiedDate: 2021-06-04T06:27:12Z - format: iso - errorMessage: Error downloading image from provided URL - description: Ubuntu Server 20.04.2 LTS - sizeMb: 1024 - creationDate: 2021-06-03T06:27:12Z - version: 20.04.2 - url: https://example.com/image.qcow2 - uploadedSizeMb: 1024 + customerId: "54321" + id: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + secret: 7271e905-239e-4d15-a8c5-527743a58390 + - clientId: DE-54321 tenantId: DE - customerId: "12345" - name: Custom Image Ubuntu - osType: Linux - status: Pending - standardImage: true + customerId: "54321" + id: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 + secret: 7271e905-239e-4d15-a8c5-527743a58390 _links: - self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + self: /v1/users/client properties: data: items: - $ref: '#/components/schemas/ImageResponse' + $ref: '#/components/schemas/ClientResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + self: /v1/users/client required: - _links - data type: object - UpdateCustomImageRequest: - example: - name: Ubuntu Custom Image - description: Ubuntu 20.04 image - properties: - name: - description: Image Name - example: Ubuntu Custom Image - type: string - description: - description: Image Description - example: Ubuntu 20.04 image - type: string - type: object - UpdateCustomImageResponseData: + ClientSecretResponse: example: - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d tenantId: DE customerId: "54321" + secret: 7271e905-239e-4d15-a8c5-527743a58390 properties: tenantId: description: Your customer tenant id @@ -15009,48 +15022,45 @@ components: example: "54321" minLength: 1 type: string - imageId: - description: Image's id - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + secret: + description: IDM client secret + example: 7271e905-239e-4d15-a8c5-527743a58390 type: string required: - customerId - - imageId + - secret - tenantId type: object - UpdateCustomImageResponse: + GenerateClientSecretResponse: example: data: - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - tenantId: DE + - tenantId: DE customerId: "54321" - - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - tenantId: DE + secret: 7271e905-239e-4d15-a8c5-527743a58390 + - tenantId: DE customerId: "54321" + secret: 7271e905-239e-4d15-a8c5-527743a58390 _links: - self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + self: /v1/users/client/secret properties: data: items: - $ref: '#/components/schemas/UpdateCustomImageResponseData' + $ref: '#/components/schemas/ClientSecretResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/images/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d + self: /v1/users/client/secret required: - _links - data type: object - CustomImagesStatsResponseData: + UserIsPasswordSetResponse: example: - currentImagesCount: 4 - usedSizeMb: 55000 tenantId: DE customerId: "54321" - freeSizeMb: 47400 - totalSizeMb: 102400 + isPasswordSet: false properties: tenantId: description: Your customer tenant id @@ -15062,164 +15072,101 @@ components: example: "54321" minLength: 1 type: string - currentImagesCount: - description: The number of existing custom images - example: 4 - type: number - totalSizeMb: - description: Total available disk space in MB - example: 102400 - type: number - usedSizeMb: - description: Used disk space in MB - example: 55000 - type: number - freeSizeMb: - description: Free disk space in MB - example: 47400 - type: number + isPasswordSet: + description: Indicates if the user has set a password for his account + example: false + type: boolean required: - - currentImagesCount - customerId - - freeSizeMb + - isPasswordSet - tenantId - - totalSizeMb - - usedSizeMb type: object - CustomImagesStatsResponse: + FindUserIsPasswordSetResponse: example: data: - - currentImagesCount: 4 - usedSizeMb: 55000 - tenantId: DE + - tenantId: DE customerId: "54321" - freeSizeMb: 47400 - totalSizeMb: 102400 - - currentImagesCount: 4 - usedSizeMb: 55000 - tenantId: DE + isPasswordSet: false + - tenantId: DE customerId: "54321" - freeSizeMb: 47400 - totalSizeMb: 102400 + isPasswordSet: false _links: - self: /v1/compute/images/stats + self: /v1/users/is-password-set properties: data: items: - $ref: '#/components/schemas/CustomImagesStatsResponseData' + $ref: '#/components/schemas/UserIsPasswordSetResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/images/stats + self: /v1/users/is-password-set required: - _links - data type: object - SnapshotResponse: - example: - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 - tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description - properties: - tenantId: - description: Your customer tenant id - example: DE - minLength: 1 - type: string - customerId: - description: Your customer number - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - minLength: 1 - type: string - snapshotId: - description: Snapshot's id - example: snap1628603855 - type: string - name: - description: The name of the snapshot. - example: Snapshot-Server - maxLength: 255 - minLength: 1 - type: string - description: - description: The description of the snapshot. - example: Snapshot-Description - maxLength: 255 - minLength: 1 - type: string - instanceId: - description: The instance identifier associated with the snapshot - example: 1234 - format: int64 - type: integer - createdDate: - description: The date when the snapshot was created - example: 2021-06-02T12:32:03.363Z - format: date-time - type: string - autoDeleteDate: - description: The date when the snapshot will be auto-deleted - example: 2021-07-02T12:32:03.363Z - format: date-time - type: string - imageId: - description: Image Id the snapshot was taken on - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - type: string - imageName: - description: Image name the snapshot was taken on - example: ubuntu-18.04 - type: string - required: - - autoDeleteDate - - createdDate - - customerId - - description - - imageId - - imageName - - instanceId - - name - - snapshotId - - tenantId - type: object - ListSnapshotResponse: + ListRoleResponse: example: data: - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 + customerId: "54321" + name: infrastructure + admin: true + type: custom + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description + customerId: "54321" + name: infrastructure + admin: true + type: custom _links: - first: /v1/compute/instances/12345/snapshots?page=1 - next: /v1/compute/instances/12345/snapshots?page=19 - self: /v1/compute/instances/12345/snapshots/snap1628603855 - previous: /v1/compute/instances/12345/snapshots?page=21 - last: /v1/compute/instances/12345/snapshots?page=101 + first: /v1/role/{roleType}/?page=1 + next: /v1/role/{roleType}/?page=19 + self: /v1/role/{roleType}/12345 + previous: /v1/role/{roleType}/?page=21 + last: /v1/role/{roleType}?page=101 _pagination: "" properties: _pagination: @@ -15228,320 +15175,451 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/SnapshotResponse' + $ref: '#/components/schemas/RoleResponse' + type: array + _links: + allOf: + - $ref: '#/components/schemas/Links' + example: + first: /v1/role/{roleType}/?page=1 + next: /v1/role/{roleType}/?page=19 + self: /v1/role/{roleType}/12345 + previous: /v1/role/{roleType}/?page=21 + last: /v1/role/{roleType}?page=101 + required: + - _links + - _pagination + - data + type: object + PermissionRequest: + example: + apiName: infrastructure + resources: + - 1 + - 2 + - 3 + actions: + - CREATE + - READ + properties: + apiName: + description: The name of the role. There is a limit of 255 characters per + role. + example: infrastructure + maxLength: 255 + minLength: 1 + type: string + actions: + description: Action allowed for the API endpoint. Basically `CREATE` corresponds + to POST endpoints, `READ` to GET endpoints, `UPDATE` to PATCH / PUT endpoints + and `DELETE` to DELETE endpoints. + example: + - CREATE + - READ + items: + enum: + - CREATE + - READ + - UPDATE + - DELETE + type: string type: array - _links: - allOf: - - $ref: '#/components/schemas/Links' + resources: + description: The IDs of tags. Only if those tags are assgined to a resource + the user with that role will be able to access the resource. example: - first: /v1/compute/instances/12345/snapshots?page=1 - next: /v1/compute/instances/12345/snapshots?page=19 - self: /v1/compute/instances/12345/snapshots/snap1628603855 - previous: /v1/compute/instances/12345/snapshots?page=21 - last: /v1/compute/instances/12345/snapshots?page=101 + - 1 + - 2 + - 3 + items: + format: int64 + type: integer + type: array required: - - _links - - _pagination - - data + - actions + - apiName type: object - CreateSnapshotRequest: + CreateRoleRequest: example: - name: Snapshot-Server - description: Snapshot-Description + permissions: + - apiName: infrastructure + resources: + - 1 + - 2 + - 3 + actions: + - CREATE + - READ + - apiName: infrastructure + resources: + - 1 + - 2 + - 3 + actions: + - CREATE + - READ + accessAllResources: false + name: infrastructure + admin: false properties: name: - description: The name of the snapshot. It may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - snapshot. - example: Snapshot-Server - maxLength: 255 - minLength: 1 - type: string - description: - description: The description of the snapshot. There is a limit of 255 characters - per snapshot. - example: Snapshot-Description + description: The name of the role. There is a limit of 255 characters per + role. + example: infrastructure maxLength: 255 minLength: 1 type: string + admin: + description: If user is admin he will have permissions to all API endpoints + and resources. Enabling this will superseed all role definitions and `accessAllResources`. + example: false + type: boolean + accessAllResources: + description: Allow access to all resources. This will superseed all assigned + resources in a role. + example: false + type: boolean + permissions: + items: + $ref: '#/components/schemas/PermissionRequest' + type: array required: + - accessAllResources + - admin - name type: object - CreateSnapshotResponse: + CreateRoleResponseData: example: - data: - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 - tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 - tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description - _links: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + roleId: 12345 + tenantId: DE + customerId: "54321" properties: - data: - items: - $ref: '#/components/schemas/SnapshotResponse' - type: array - _links: - allOf: - - $ref: '#/components/schemas/SelfLinks' - example: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + tenantId: + description: Your customer tenant id + example: DE + minLength: 1 + type: string + customerId: + description: Your customer number + example: "54321" + minLength: 1 + type: string + roleId: + description: Role's id + example: 12345 + format: int64 + type: integer required: - - _links - - data + - customerId + - roleId + - tenantId type: object - FindSnapshotResponse: + CreateRoleResponse: example: data: - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 + - roleId: 12345 tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 + customerId: "54321" + - roleId: 12345 tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description + customerId: "54321" _links: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + self: /v1/roles/12345 properties: data: items: - $ref: '#/components/schemas/SnapshotResponse' + $ref: '#/components/schemas/CreateRoleResponseData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + self: /v1/roles/12345 required: - _links - data type: object - UpdateSnapshotRequest: - example: - name: Snapshot-Server - description: Snapshot-Description - properties: - name: - description: The name of the snapshot. Tags may contain letters, numbers, - colons, dashes, and underscores. There is a limit of 255 characters per - snapshot. - example: Snapshot-Server - maxLength: 255 - minLength: 1 - type: string - description: - description: The description of the snapshot. There is a limit of 255 characters - per snapshot. - example: Snapshot-Description - maxLength: 255 - minLength: 1 - type: string - type: object - UpdateSnapshotResponse: + FindRoleResponse: example: data: - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description - - snapshotId: snap1628603855 - instanceId: 1234 - createdDate: 2021-06-02T12:32:03.363Z - autoDeleteDate: 2021-07-02T12:32:03.363Z - imageId: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - imageName: ubuntu-18.04 + customerId: "54321" + name: infrastructure + admin: true + type: custom + - roleId: 12345 + permissions: + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + resources: + - tagId: 12345 + tagName: Web + - tagId: 12345 + tagName: Web + actions: + - CREATE + - READ + accessAllResources: true tenantId: DE - customerId: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - name: Snapshot-Server - description: Snapshot-Description + customerId: "54321" + name: infrastructure + admin: true + type: custom _links: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + self: /v1/roles/12345 properties: data: items: - $ref: '#/components/schemas/SnapshotResponse' + $ref: '#/components/schemas/RoleResponse' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + self: /v1/roles/12345 required: - _links - data type: object - RollbackSnapshotRequest: - properties: {} + UpdateRoleRequest: + example: + permissions: + - apiName: infrastructure + resources: + - 1 + - 2 + - 3 + actions: + - CREATE + - READ + - apiName: infrastructure + resources: + - 1 + - 2 + - 3 + actions: + - CREATE + - READ + accessAllResources: false + name: infrastructure + admin: false + properties: + name: + description: The name of the role. There is a limit of 255 characters per + role. + example: infrastructure + maxLength: 255 + minLength: 1 + type: string + admin: + description: If user is admin he will have permissions to all API endpoints + and resources. Enabling this will superseed all role definitions and `accessAllResources`. + example: false + type: boolean + accessAllResources: + description: Allow access to all resources. This will superseed all assigned + resources in a role. + example: false + type: boolean + permissions: + items: + $ref: '#/components/schemas/PermissionRequest' + type: array + required: + - accessAllResources + - admin + - name type: object - RollbackSnapshotResponse: + UpdateRoleResponse: example: _links: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + self: /v1/roles/12345 properties: _links: allOf: - $ref: '#/components/schemas/SelfLinks' description: Links for easy navigation. example: - self: /v1/compute/instances/12345/snapshots/snap1628603855 + self: /v1/roles/12345 required: - _links type: object - ApplicationConfig: + ApiPermissionsResponse: + example: + apiName: /v1/compute/instances + actions: + - CREATE + - READ properties: - imageId: - description: Image ID - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - type: string - userDataId: - description: User Data ID - example: 8b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - type: string - userData: - description: '[Cloud-Init](https://cloud-init.io/) Config in order to customize - during start of compute instance.' - example: |- - #cloud-config - user: admin - timezone: Europe/Berlin - chpasswd: - expire: False + apiName: + description: API endpoint. In order to get a list availbale api enpoints + please refer to the GET api-permissions endpoint. + example: /v1/compute/instances type: string + actions: + description: Action allowed for the API endpoint. Basically `CREATE` corresponds + to POST endpoints, `READ` to GET endpoints, `UPDATE` to PATCH / PUT endpoints + and `DELETE` to DELETE endpoints. + example: + - CREATE + - READ + items: + enum: + - CREATE + - READ + - UPDATE + - DELETE + type: string + type: array required: - - imageId - - userData - - userDataId - type: object - MinimumRequirements: - properties: - cpuCores: - description: CPU Cores Requirement - example: 2 - type: number - ramMb: - description: Memory Requirement in MB - example: 100 - type: number - diskMb: - description: Storage Requirement in MB - example: 500 - type: number - type: object - OptimalRequirements: - properties: - cpuCores: - description: CPU Cores Requirement - example: 2 - type: number - ramMb: - description: Memory Requirement in MB - example: 100 - type: number - diskMb: - description: Storage Requirement in MB - example: 500 - type: number + - actions + - apiName type: object - ApplicationRequirements: + ListApiPermissionResponse: + example: + data: + - apiName: /v1/compute/instances + actions: + - CREATE + - READ + - apiName: /v1/compute/instances + actions: + - CREATE + - READ + _links: + first: /v1/roles/api-permissions?page=1 + previous: /v1/roles/api-permissions?page=2 + next: /v1/roles/api-permissions?page=3 + last: /v1/roles/api-permissions?page=10 + self: /v1/roles/api-permissions properties: - minimum: - allOf: - - $ref: '#/components/schemas/MinimumRequirements' - description: Application minimum requirements - optimal: + data: + items: + $ref: '#/components/schemas/ApiPermissionsResponse' + type: array + _links: allOf: - - $ref: '#/components/schemas/OptimalRequirements' - description: Application optimal requirements + - $ref: '#/components/schemas/Links' + example: + first: /v1/roles/api-permissions?page=1 + previous: /v1/roles/api-permissions?page=2 + next: /v1/roles/api-permissions?page=3 + last: /v1/roles/api-permissions?page=10 + self: /v1/roles/api-permissions + required: + - _links + - data type: object - ApplicationResponse: + CredentialData: + example: + objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y + secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY + accessKey: AKIAIOSFODNN7EXAMPLE + displayName: Object Storage Test + tenantId: DE + customerId: "54321" + credentialId: 12345 + region: European Union (Germany) properties: - applicationId: - description: Application ID - example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d - type: string tenantId: - description: Tenant ID - enum: - - DE - - INT + description: Your customer tenant id example: DE minLength: 1 type: string customerId: - description: Customer ID - example: "12345" + description: Your customer number + example: "54321" minLength: 1 type: string - name: - description: Application Name - example: Webmin + accessKey: + description: Access key ID. + example: AKIAIOSFODNN7EXAMPLE type: string - description: - description: Application Description - example: Webmin cloud init + secretKey: + description: Secret key ID. + example: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY type: string - type: - description: Application type - enum: - - standard - - crypto - example: standard + objectStorageId: + description: Object Storage ID. + example: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y type: string - applicationConfig: - description: Application Config - items: - $ref: '#/components/schemas/ApplicationConfig' - type: array - requirements: - allOf: - - $ref: '#/components/schemas/ApplicationRequirements' - description: Application Requirements + displayName: + description: Object Storage Name. + example: Object Storage Test + type: string + region: + description: Object Storage Region. + example: European Union (Germany) + type: string + credentialId: + description: Object Storage Credential ID + example: 12345 + type: number required: - - applicationConfig - - applicationId + - accessKey + - credentialId - customerId - - description - - name - - requirements + - displayName + - objectStorageId + - region + - secretKey - tenantId - - type type: object - ListApplicationsResponse: + ListCredentialResponse: + example: + data: + - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y + secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY + accessKey: AKIAIOSFODNN7EXAMPLE + displayName: Object Storage Test + tenantId: DE + customerId: "54321" + credentialId: 12345 + region: European Union (Germany) + - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y + secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY + accessKey: AKIAIOSFODNN7EXAMPLE + displayName: Object Storage Test + tenantId: DE + customerId: "54321" + credentialId: 12345 + region: European Union (Germany) + _links: + first: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=1 + next: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=19 + self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials/12345 + previous: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=21 + last: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=101 + _pagination: "" properties: _pagination: allOf: @@ -15549,91 +15627,61 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/ApplicationResponse' + $ref: '#/components/schemas/CredentialData' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/compute/applications?page=1 - previous: /v1/compute/applications?page=19 - self: /v1/compute/applications?page=20 - next: /v1/compute/applications?page=21 - last: /v1/compute/applications?page=101 + first: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=1 + next: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=19 + self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials/12345 + previous: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=21 + last: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/credentials?page=101 required: - _links - _pagination - data type: object - VncResponse: - properties: - tenantId: - description: Your customer tenant id - enum: - - DE - - INT - example: DE - minLength: 1 - type: string - customerId: - description: Customer ID - example: 3f184ab8-a600-4e7c-8c9b-3413e21a3752 - minLength: 1 - type: string - instanceId: - description: Instance ID - example: 100 - format: int64 - type: integer - enabled: - description: VNC Status for the instance. - example: true - type: boolean - vncIp: - description: VNC IP for the instance. - example: 154.12.54.123 - type: string - vncPort: - description: VNC Port for the instance. - example: 8001 - type: number - required: - - customerId - - enabled - - instanceId - - tenantId - - vncIp - - vncPort - type: object - FindVncResponse: + FindCredentialResponse: + example: + data: + - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y + secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY + accessKey: AKIAIOSFODNN7EXAMPLE + displayName: Object Storage Test + tenantId: DE + customerId: "54321" + credentialId: 12345 + region: European Union (Germany) + - objectStorageId: 9a4c7e20-c326-4a8c-900c-687ad83ba170Y + secretKey: wJalrXK7MDENGbPxRfiCYEXAMPLEKEY + accessKey: AKIAIOSFODNN7EXAMPLE + displayName: Object Storage Test + tenantId: DE + customerId: "54321" + credentialId: 12345 + region: European Union (Germany) + _links: + self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/e3f0207c-f7fe-433a-92ab-39a9e976642d/credentials properties: data: items: - $ref: '#/components/schemas/VncResponse' + $ref: '#/components/schemas/CredentialData' type: array _links: allOf: - $ref: '#/components/schemas/SelfLinks' example: - self: /v1/compute/instances/100/vnc + self: v1/users/08a92037-01e8-4dff-8565-47cad7be701a/object-storages/e3f0207c-f7fe-433a-92ab-39a9e976642d/credentials required: - _links - data type: object - PatchVncRequest: - properties: - vncPassword: - description: Password for instance VNC - example: test123 - type: string - required: - - vncPassword - type: object - ImageAuditResponseData: + UserAuditResponse: example: traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - imageId: e443eab5-647a-4bc3-b4f9-16f5a281224d - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" @@ -15644,11 +15692,12 @@ components: name: test1 action: CREATED id: 12345 + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 timestamp: 2021-03-30T11:35:06.177Z username: John.Doe properties: id: - description: The ID of the audit entry. + description: The identifier of the audit entry. example: 12345 format: int64 type: integer @@ -15671,13 +15720,13 @@ components: minLength: 1 type: string customerId: - description: Customer ID + description: Customer number example: "54321" minLength: 1 type: string changedBy: - description: Id of user who performed the change - example: c4c800ff-e524-47dd-9543-71dfc8b91113 + description: User ID + example: "54321" minLength: 1 type: string username: @@ -15692,9 +15741,9 @@ components: description: The traceId of the API call which led to the change. example: 78E9A428-94E9-4A2A-92F5-26038C6884F type: string - imageId: - description: The identifier of the image - example: e443eab5-647a-4bc3-b4f9-16f5a281224d + userId: + description: The identifier of the user + example: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 type: string changes: description: List of actual changes. @@ -15709,19 +15758,18 @@ components: - changedBy - customerId - id - - imageId - requestId - tenantId - timestamp - traceId + - userId - username type: object - ImageAuditResponse: + ListUserAuditResponse: example: data: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - imageId: e443eab5-647a-4bc3-b4f9-16f5a281224d - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" @@ -15732,11 +15780,11 @@ components: name: test1 action: CREATED id: 12345 + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 timestamp: 2021-03-30T11:35:06.177Z username: John.Doe - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - imageId: e443eab5-647a-4bc3-b4f9-16f5a281224d - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 tenantId: DE customerId: "54321" @@ -15747,14 +15795,15 @@ components: name: test1 action: CREATED id: 12345 + userId: 6cdf5968-f9fe-4192-97c2-f349e813c5e8 timestamp: 2021-03-30T11:35:06.177Z username: John.Doe _links: - first: /v1/compute/images/audits?page=2 - previous: /v1/compute/images/audits?page=2 - next: /v1/compute/images/audits?page=3 - last: /v1/compute/images/audits?page=10 - self: /v1/compute/images/audits + first: /v1/users/audits?page=2 + previous: /v1/users/audits?page=2 + next: /v1/users/audits?page=3 + last: /v1/users/audits?page=10 + self: /v1/users/audits _pagination: "" properties: _pagination: @@ -15763,29 +15812,28 @@ components: description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/ImageAuditResponseData' + $ref: '#/components/schemas/UserAuditResponse' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/compute/images/audits?page=2 - previous: /v1/compute/images/audits?page=2 - next: /v1/compute/images/audits?page=3 - last: /v1/compute/images/audits?page=10 - self: /v1/compute/images/audits + first: /v1/users/audits?page=2 + previous: /v1/users/audits?page=2 + next: /v1/users/audits?page=3 + last: /v1/users/audits?page=10 + self: /v1/users/audits required: - _links - _pagination - data type: object - SnapshotsAuditResponse: + RoleAuditResponse: example: traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - snapshotId: snap1628603855 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + roleId: 12345 tenantId: DE customerId: "54321" changes: @@ -15799,7 +15847,7 @@ components: username: John.Doe properties: id: - description: The ID of the audit entry. + description: The identifier of the audit entry. example: 12345 format: int64 type: integer @@ -15822,13 +15870,13 @@ components: minLength: 1 type: string customerId: - description: Customer ID + description: Customer number example: "54321" minLength: 1 type: string changedBy: - description: Id of user who performed the change - example: c4c800ff-e524-47dd-9543-71dfc8b91113 + description: User ID + example: "54321" minLength: 1 type: string username: @@ -15843,18 +15891,13 @@ components: description: The traceId of the API call which led to the change. example: 78E9A428-94E9-4A2A-92F5-26038C6884F type: string - instanceId: - description: The identifier of the instance + roleId: + description: The identifier of the role example: 12345 - format: int64 minimum: 0 - type: integer - snapshotId: - description: The identifier of the snapshot - example: snap1628603855 - type: string + type: number changes: - description: List of actual changes + description: List of actual changes. example: prev: name: test @@ -15866,22 +15909,20 @@ components: - changedBy - customerId - id - - instanceId - requestId - - snapshotId + - roleId - tenantId - timestamp - traceId - username type: object - ListSnapshotsAuditResponse: + ListRoleAuditResponse: example: data: - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - snapshotId: snap1628603855 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + roleId: 12345 tenantId: DE customerId: "54321" changes: @@ -15894,10 +15935,9 @@ components: timestamp: 2021-03-30T11:35:06.177Z username: John.Doe - traceId: 78E9A428-94E9-4A2A-92F5-26038C6884F - instanceId: 12345 - snapshotId: snap1628603855 - changedBy: c4c800ff-e524-47dd-9543-71dfc8b91113 + changedBy: "54321" requestId: A2F56FAF-18N0-4893-11HG-R312M1E4FEC5 + roleId: 12345 tenantId: DE customerId: "54321" changes: @@ -15910,33 +15950,27 @@ components: timestamp: 2021-03-30T11:35:06.177Z username: John.Doe _links: - first: /v1/compute/snapshots/audits?page=2 - previous: /v1/compute/snapshots/audits?page=2 - next: /v1/compute/snapshots/audits?page=3 - last: /v1/compute/snapshots/audits?page=10 - self: /v1/compute/snapshots/audits - _pagination: "" + first: /v1/roles/audits?page=2 + previous: /v1/roles/audits?page=2 + next: /v1/roles/audits?page=3 + last: /v1/roles/audits?page=10 + self: /v1/roles/audits properties: - _pagination: - allOf: - - $ref: '#/components/schemas/PaginationMeta' - description: Data about pagination like how many results, pages, page size. data: items: - $ref: '#/components/schemas/SnapshotsAuditResponse' + $ref: '#/components/schemas/RoleAuditResponse' type: array _links: allOf: - $ref: '#/components/schemas/Links' example: - first: /v1/compute/snapshots/audits?page=2 - previous: /v1/compute/snapshots/audits?page=2 - next: /v1/compute/snapshots/audits?page=3 - last: /v1/compute/snapshots/audits?page=10 - self: /v1/compute/snapshots/audits + first: /v1/roles/audits?page=2 + previous: /v1/roles/audits?page=2 + next: /v1/roles/audits?page=3 + last: /v1/roles/audits?page=10 + self: /v1/roles/audits required: - _links - - _pagination - data type: object securitySchemes: diff --git a/openapi/api_images.go b/openapi/api_images.go index d59bcf5..4a859da 100644 --- a/openapi/api_images.go +++ b/openapi/api_images.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_images_audits.go b/openapi/api_images_audits.go index 39c0c79..6dedac9 100644 --- a/openapi/api_images_audits.go +++ b/openapi/api_images_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_instance_actions.go b/openapi/api_instance_actions.go index ea34b79..4ec4df8 100644 --- a/openapi/api_instance_actions.go +++ b/openapi/api_instance_actions.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_instance_actions_audits.go b/openapi/api_instance_actions_audits.go index 7a7271f..a9ddab3 100644 --- a/openapi/api_instance_actions_audits.go +++ b/openapi/api_instance_actions_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_instances.go b/openapi/api_instances.go index c370386..9874cbc 100644 --- a/openapi/api_instances.go +++ b/openapi/api_instances.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_instances_audits.go b/openapi/api_instances_audits.go index 8254d38..ce5632b 100644 --- a/openapi/api_instances_audits.go +++ b/openapi/api_instances_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_internal.go b/openapi/api_internal.go index 73cbbd0..75ff24d 100644 --- a/openapi/api_internal.go +++ b/openapi/api_internal.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_object_storages.go b/openapi/api_object_storages.go index d26f705..2c59a07 100644 --- a/openapi/api_object_storages.go +++ b/openapi/api_object_storages.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_object_storages_audits.go b/openapi/api_object_storages_audits.go index d486219..183f942 100644 --- a/openapi/api_object_storages_audits.go +++ b/openapi/api_object_storages_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_private_networks.go b/openapi/api_private_networks.go index 9df8f0c..5e8f029 100644 --- a/openapi/api_private_networks.go +++ b/openapi/api_private_networks.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_private_networks_audits.go b/openapi/api_private_networks_audits.go index f808924..b26ba0d 100644 --- a/openapi/api_private_networks_audits.go +++ b/openapi/api_private_networks_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_roles.go b/openapi/api_roles.go index 44a6282..0ceb698 100644 --- a/openapi/api_roles.go +++ b/openapi/api_roles.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_roles_audits.go b/openapi/api_roles_audits.go index 735116e..dc41952 100644 --- a/openapi/api_roles_audits.go +++ b/openapi/api_roles_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_secrets.go b/openapi/api_secrets.go index d254a27..d307001 100644 --- a/openapi/api_secrets.go +++ b/openapi/api_secrets.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_secrets_audits.go b/openapi/api_secrets_audits.go index 23ed461..0fc06c6 100644 --- a/openapi/api_secrets_audits.go +++ b/openapi/api_secrets_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_snapshots.go b/openapi/api_snapshots.go index a6ca75a..0e2a293 100644 --- a/openapi/api_snapshots.go +++ b/openapi/api_snapshots.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_snapshots_audits.go b/openapi/api_snapshots_audits.go index 6cf84fc..3a27693 100644 --- a/openapi/api_snapshots_audits.go +++ b/openapi/api_snapshots_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_tag_assignments.go b/openapi/api_tag_assignments.go index 40691b1..7b4e346 100644 --- a/openapi/api_tag_assignments.go +++ b/openapi/api_tag_assignments.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_tag_assignments_audits.go b/openapi/api_tag_assignments_audits.go index 33078bd..3c5d88d 100644 --- a/openapi/api_tag_assignments_audits.go +++ b/openapi/api_tag_assignments_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_tags.go b/openapi/api_tags.go index 681a8e7..c731694 100644 --- a/openapi/api_tags.go +++ b/openapi/api_tags.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_tags_audits.go b/openapi/api_tags_audits.go index 5bb99b6..cca78f5 100644 --- a/openapi/api_tags_audits.go +++ b/openapi/api_tags_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_tickets.go b/openapi/api_tickets.go index cbe7e8d..5d3510b 100644 --- a/openapi/api_tickets.go +++ b/openapi/api_tickets.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_users.go b/openapi/api_users.go index a683154..1d6f51b 100644 --- a/openapi/api_users.go +++ b/openapi/api_users.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/api_users_audits.go b/openapi/api_users_audits.go index 16ac641..7793eda 100644 --- a/openapi/api_users_audits.go +++ b/openapi/api_users_audits.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/client.go b/openapi/client.go index 56edf5f..ed9e2ff 100644 --- a/openapi/client.go +++ b/openapi/client.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/configuration.go b/openapi/configuration.go index a64036f..d05b873 100644 --- a/openapi/configuration.go +++ b/openapi/configuration.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/docs/FindTagResponse.md b/openapi/docs/FindTagResponse.md index dbc164c..58a21e6 100644 --- a/openapi/docs/FindTagResponse.md +++ b/openapi/docs/FindTagResponse.md @@ -4,14 +4,14 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**Data** | [**[]TagResponse**](TagResponse.md) | | +**Data** | [**[]TagResponse1**](TagResponse1.md) | | **Links** | [**SelfLinks**](SelfLinks.md) | | ## Methods ### NewFindTagResponse -`func NewFindTagResponse(data []TagResponse, links SelfLinks, ) *FindTagResponse` +`func NewFindTagResponse(data []TagResponse1, links SelfLinks, ) *FindTagResponse` NewFindTagResponse instantiates a new FindTagResponse object This constructor will assign default values to properties that have it defined, @@ -28,20 +28,20 @@ but it doesn't guarantee that properties required by API are set ### GetData -`func (o *FindTagResponse) GetData() []TagResponse` +`func (o *FindTagResponse) GetData() []TagResponse1` GetData returns the Data field if non-nil, zero value otherwise. ### GetDataOk -`func (o *FindTagResponse) GetDataOk() (*[]TagResponse, bool)` +`func (o *FindTagResponse) GetDataOk() (*[]TagResponse1, bool)` GetDataOk returns a tuple with the Data field if it's non-nil, zero value otherwise and a boolean to check if the value has been set. ### SetData -`func (o *FindTagResponse) SetData(v []TagResponse)` +`func (o *FindTagResponse) SetData(v []TagResponse1)` SetData sets Data field to given value. diff --git a/openapi/docs/InstanceResponse.md b/openapi/docs/InstanceResponse.md index 65df64d..e5ed1c4 100644 --- a/openapi/docs/InstanceResponse.md +++ b/openapi/docs/InstanceResponse.md @@ -26,6 +26,8 @@ Name | Type | Description | Notes **CancelDate** | **string** | The date on which the instance will be cancelled | **Status** | [**InstanceStatus**](InstanceStatus.md) | | **VHostId** | **int64** | ID of host system | +**VHostNumber** | **int64** | Number of host system | +**VHostName** | **string** | Name of host system | **AddOns** | [**[]AddOnResponse**](AddOnResponse.md) | | **ErrorMessage** | Pointer to **string** | Message in case of an error. | [optional] **ProductType** | **string** | Instance's category depending on Product Id | @@ -36,7 +38,7 @@ Name | Type | Description | Notes ### NewInstanceResponse -`func NewInstanceResponse(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, addOns []AddOnResponse, productType string, productName string, ) *InstanceResponse` +`func NewInstanceResponse(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, vHostNumber int64, vHostName string, addOns []AddOnResponse, productType string, productName string, ) *InstanceResponse` NewInstanceResponse instantiates a new InstanceResponse object This constructor will assign default values to properties that have it defined, @@ -491,6 +493,46 @@ and a boolean to check if the value has been set. SetVHostId sets VHostId field to given value. +### GetVHostNumber + +`func (o *InstanceResponse) GetVHostNumber() int64` + +GetVHostNumber returns the VHostNumber field if non-nil, zero value otherwise. + +### GetVHostNumberOk + +`func (o *InstanceResponse) GetVHostNumberOk() (*int64, bool)` + +GetVHostNumberOk returns a tuple with the VHostNumber field if it's non-nil, zero value otherwise +and a boolean to check if the value has been set. + +### SetVHostNumber + +`func (o *InstanceResponse) SetVHostNumber(v int64)` + +SetVHostNumber sets VHostNumber field to given value. + + +### GetVHostName + +`func (o *InstanceResponse) GetVHostName() string` + +GetVHostName returns the VHostName field if non-nil, zero value otherwise. + +### GetVHostNameOk + +`func (o *InstanceResponse) GetVHostNameOk() (*string, bool)` + +GetVHostNameOk returns a tuple with the VHostName field if it's non-nil, zero value otherwise +and a boolean to check if the value has been set. + +### SetVHostName + +`func (o *InstanceResponse) SetVHostName(v string)` + +SetVHostName sets VHostName field to given value. + + ### GetAddOns `func (o *InstanceResponse) GetAddOns() []AddOnResponse` diff --git a/openapi/docs/ListImageResponseData.md b/openapi/docs/ListImageResponseData.md index ae796aa..188c663 100644 --- a/openapi/docs/ListImageResponseData.md +++ b/openapi/docs/ListImageResponseData.md @@ -20,13 +20,13 @@ Name | Type | Description | Notes **StandardImage** | **bool** | Flag indicating that image is either a standard (true) or a custom image (false) | **CreationDate** | **time.Time** | The creation date time for the image | **LastModifiedDate** | **time.Time** | The last modified date time for the image | -**Tags** | [**[]TagResponse1**](TagResponse1.md) | The tags assigned to the image | +**Tags** | [**[]TagResponse**](TagResponse.md) | The tags assigned to the image | ## Methods ### NewListImageResponseData -`func NewListImageResponseData(imageId string, tenantId string, customerId string, name string, description string, url string, sizeMb float32, uploadedSizeMb float32, osType string, version string, format string, status string, errorMessage string, standardImage bool, creationDate time.Time, lastModifiedDate time.Time, tags []TagResponse1, ) *ListImageResponseData` +`func NewListImageResponseData(imageId string, tenantId string, customerId string, name string, description string, url string, sizeMb float32, uploadedSizeMb float32, osType string, version string, format string, status string, errorMessage string, standardImage bool, creationDate time.Time, lastModifiedDate time.Time, tags []TagResponse, ) *ListImageResponseData` NewListImageResponseData instantiates a new ListImageResponseData object This constructor will assign default values to properties that have it defined, @@ -363,20 +363,20 @@ SetLastModifiedDate sets LastModifiedDate field to given value. ### GetTags -`func (o *ListImageResponseData) GetTags() []TagResponse1` +`func (o *ListImageResponseData) GetTags() []TagResponse` GetTags returns the Tags field if non-nil, zero value otherwise. ### GetTagsOk -`func (o *ListImageResponseData) GetTagsOk() (*[]TagResponse1, bool)` +`func (o *ListImageResponseData) GetTagsOk() (*[]TagResponse, bool)` GetTagsOk returns a tuple with the Tags field if it's non-nil, zero value otherwise and a boolean to check if the value has been set. ### SetTags -`func (o *ListImageResponseData) SetTags(v []TagResponse1)` +`func (o *ListImageResponseData) SetTags(v []TagResponse)` SetTags sets Tags field to given value. diff --git a/openapi/docs/ListInstancesResponseData.md b/openapi/docs/ListInstancesResponseData.md index 3a735c2..d93c684 100644 --- a/openapi/docs/ListInstancesResponseData.md +++ b/openapi/docs/ListInstancesResponseData.md @@ -26,6 +26,8 @@ Name | Type | Description | Notes **CancelDate** | **string** | The date on which the instance will be cancelled | **Status** | [**InstanceStatus**](InstanceStatus.md) | | **VHostId** | **int64** | ID of host system | +**VHostNumber** | **int64** | Number of host system | +**VHostName** | **string** | Name of host system | **AddOns** | [**[]AddOnResponse**](AddOnResponse.md) | | **ErrorMessage** | Pointer to **string** | Message in case of an error. | [optional] **ProductType** | **string** | Instance's category depending on Product Id | @@ -36,7 +38,7 @@ Name | Type | Description | Notes ### NewListInstancesResponseData -`func NewListInstancesResponseData(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, addOns []AddOnResponse, productType string, productName string, ) *ListInstancesResponseData` +`func NewListInstancesResponseData(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, vHostNumber int64, vHostName string, addOns []AddOnResponse, productType string, productName string, ) *ListInstancesResponseData` NewListInstancesResponseData instantiates a new ListInstancesResponseData object This constructor will assign default values to properties that have it defined, @@ -491,6 +493,46 @@ and a boolean to check if the value has been set. SetVHostId sets VHostId field to given value. +### GetVHostNumber + +`func (o *ListInstancesResponseData) GetVHostNumber() int64` + +GetVHostNumber returns the VHostNumber field if non-nil, zero value otherwise. + +### GetVHostNumberOk + +`func (o *ListInstancesResponseData) GetVHostNumberOk() (*int64, bool)` + +GetVHostNumberOk returns a tuple with the VHostNumber field if it's non-nil, zero value otherwise +and a boolean to check if the value has been set. + +### SetVHostNumber + +`func (o *ListInstancesResponseData) SetVHostNumber(v int64)` + +SetVHostNumber sets VHostNumber field to given value. + + +### GetVHostName + +`func (o *ListInstancesResponseData) GetVHostName() string` + +GetVHostName returns the VHostName field if non-nil, zero value otherwise. + +### GetVHostNameOk + +`func (o *ListInstancesResponseData) GetVHostNameOk() (*string, bool)` + +GetVHostNameOk returns a tuple with the VHostName field if it's non-nil, zero value otherwise +and a boolean to check if the value has been set. + +### SetVHostName + +`func (o *ListInstancesResponseData) SetVHostName(v string)` + +SetVHostName sets VHostName field to given value. + + ### GetAddOns `func (o *ListInstancesResponseData) GetAddOns() []AddOnResponse` diff --git a/openapi/docs/ListTagResponse.md b/openapi/docs/ListTagResponse.md index 65e0afb..c9ca371 100644 --- a/openapi/docs/ListTagResponse.md +++ b/openapi/docs/ListTagResponse.md @@ -5,14 +5,14 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **Pagination** | [**PaginationMeta**](PaginationMeta.md) | Data about pagination like how many results, pages, page size. | -**Data** | [**[]TagResponse**](TagResponse.md) | | +**Data** | [**[]TagResponse1**](TagResponse1.md) | | **Links** | [**Links**](Links.md) | | ## Methods ### NewListTagResponse -`func NewListTagResponse(pagination PaginationMeta, data []TagResponse, links Links, ) *ListTagResponse` +`func NewListTagResponse(pagination PaginationMeta, data []TagResponse1, links Links, ) *ListTagResponse` NewListTagResponse instantiates a new ListTagResponse object This constructor will assign default values to properties that have it defined, @@ -49,20 +49,20 @@ SetPagination sets Pagination field to given value. ### GetData -`func (o *ListTagResponse) GetData() []TagResponse` +`func (o *ListTagResponse) GetData() []TagResponse1` GetData returns the Data field if non-nil, zero value otherwise. ### GetDataOk -`func (o *ListTagResponse) GetDataOk() (*[]TagResponse, bool)` +`func (o *ListTagResponse) GetDataOk() (*[]TagResponse1, bool)` GetDataOk returns a tuple with the Data field if it's non-nil, zero value otherwise and a boolean to check if the value has been set. ### SetData -`func (o *ListTagResponse) SetData(v []TagResponse)` +`func (o *ListTagResponse) SetData(v []TagResponse1)` SetData sets Data field to given value. diff --git a/openapi/docs/PatchInstanceRequest.md b/openapi/docs/PatchInstanceRequest.md index 95a68bc..baa798f 100644 --- a/openapi/docs/PatchInstanceRequest.md +++ b/openapi/docs/PatchInstanceRequest.md @@ -5,7 +5,6 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- **DisplayName** | Pointer to **string** | The display name of the instance | [optional] -**VncEnabled** | Pointer to **bool** | Enable/Disable the VNC option for instance | [optional] ## Methods @@ -51,31 +50,6 @@ SetDisplayName sets DisplayName field to given value. HasDisplayName returns a boolean if a field has been set. -### GetVncEnabled - -`func (o *PatchInstanceRequest) GetVncEnabled() bool` - -GetVncEnabled returns the VncEnabled field if non-nil, zero value otherwise. - -### GetVncEnabledOk - -`func (o *PatchInstanceRequest) GetVncEnabledOk() (*bool, bool)` - -GetVncEnabledOk returns a tuple with the VncEnabled field if it's non-nil, zero value otherwise -and a boolean to check if the value has been set. - -### SetVncEnabled - -`func (o *PatchInstanceRequest) SetVncEnabled(v bool)` - -SetVncEnabled sets VncEnabled field to given value. - -### HasVncEnabled - -`func (o *PatchInstanceRequest) HasVncEnabled() bool` - -HasVncEnabled returns a boolean if a field has been set. - [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/openapi/docs/TagResponse.md b/openapi/docs/TagResponse.md index 0de871a..8e2f73e 100644 --- a/openapi/docs/TagResponse.md +++ b/openapi/docs/TagResponse.md @@ -4,17 +4,14 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**TenantId** | **string** | Your customer tenant id | -**CustomerId** | **string** | Your customer number | **TagId** | **float32** | Tag's id | -**Name** | **string** | Tag's name | -**Color** | **string** | Tag's color | +**TagName** | **string** | Tag's name | ## Methods ### NewTagResponse -`func NewTagResponse(tenantId string, customerId string, tagId float32, name string, color string, ) *TagResponse` +`func NewTagResponse(tagId float32, tagName string, ) *TagResponse` NewTagResponse instantiates a new TagResponse object This constructor will assign default values to properties that have it defined, @@ -29,46 +26,6 @@ NewTagResponseWithDefaults instantiates a new TagResponse object This constructor will only assign default values to properties that have it defined, but it doesn't guarantee that properties required by API are set -### GetTenantId - -`func (o *TagResponse) GetTenantId() string` - -GetTenantId returns the TenantId field if non-nil, zero value otherwise. - -### GetTenantIdOk - -`func (o *TagResponse) GetTenantIdOk() (*string, bool)` - -GetTenantIdOk returns a tuple with the TenantId field if it's non-nil, zero value otherwise -and a boolean to check if the value has been set. - -### SetTenantId - -`func (o *TagResponse) SetTenantId(v string)` - -SetTenantId sets TenantId field to given value. - - -### GetCustomerId - -`func (o *TagResponse) GetCustomerId() string` - -GetCustomerId returns the CustomerId field if non-nil, zero value otherwise. - -### GetCustomerIdOk - -`func (o *TagResponse) GetCustomerIdOk() (*string, bool)` - -GetCustomerIdOk returns a tuple with the CustomerId field if it's non-nil, zero value otherwise -and a boolean to check if the value has been set. - -### SetCustomerId - -`func (o *TagResponse) SetCustomerId(v string)` - -SetCustomerId sets CustomerId field to given value. - - ### GetTagId `func (o *TagResponse) GetTagId() float32` @@ -89,44 +46,24 @@ and a boolean to check if the value has been set. SetTagId sets TagId field to given value. -### GetName - -`func (o *TagResponse) GetName() string` - -GetName returns the Name field if non-nil, zero value otherwise. - -### GetNameOk - -`func (o *TagResponse) GetNameOk() (*string, bool)` - -GetNameOk returns a tuple with the Name field if it's non-nil, zero value otherwise -and a boolean to check if the value has been set. - -### SetName - -`func (o *TagResponse) SetName(v string)` - -SetName sets Name field to given value. - - -### GetColor +### GetTagName -`func (o *TagResponse) GetColor() string` +`func (o *TagResponse) GetTagName() string` -GetColor returns the Color field if non-nil, zero value otherwise. +GetTagName returns the TagName field if non-nil, zero value otherwise. -### GetColorOk +### GetTagNameOk -`func (o *TagResponse) GetColorOk() (*string, bool)` +`func (o *TagResponse) GetTagNameOk() (*string, bool)` -GetColorOk returns a tuple with the Color field if it's non-nil, zero value otherwise +GetTagNameOk returns a tuple with the TagName field if it's non-nil, zero value otherwise and a boolean to check if the value has been set. -### SetColor +### SetTagName -`func (o *TagResponse) SetColor(v string)` +`func (o *TagResponse) SetTagName(v string)` -SetColor sets Color field to given value. +SetTagName sets TagName field to given value. diff --git a/openapi/docs/TagResponse1.md b/openapi/docs/TagResponse1.md index e90fbb7..5ef5ce5 100644 --- a/openapi/docs/TagResponse1.md +++ b/openapi/docs/TagResponse1.md @@ -4,14 +4,17 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- +**TenantId** | **string** | Your customer tenant id | +**CustomerId** | **string** | Your customer number | **TagId** | **float32** | Tag's id | -**TagName** | **string** | Tag's name | +**Name** | **string** | Tag's name | +**Color** | **string** | Tag's color | ## Methods ### NewTagResponse1 -`func NewTagResponse1(tagId float32, tagName string, ) *TagResponse1` +`func NewTagResponse1(tenantId string, customerId string, tagId float32, name string, color string, ) *TagResponse1` NewTagResponse1 instantiates a new TagResponse1 object This constructor will assign default values to properties that have it defined, @@ -26,6 +29,46 @@ NewTagResponse1WithDefaults instantiates a new TagResponse1 object This constructor will only assign default values to properties that have it defined, but it doesn't guarantee that properties required by API are set +### GetTenantId + +`func (o *TagResponse1) GetTenantId() string` + +GetTenantId returns the TenantId field if non-nil, zero value otherwise. + +### GetTenantIdOk + +`func (o *TagResponse1) GetTenantIdOk() (*string, bool)` + +GetTenantIdOk returns a tuple with the TenantId field if it's non-nil, zero value otherwise +and a boolean to check if the value has been set. + +### SetTenantId + +`func (o *TagResponse1) SetTenantId(v string)` + +SetTenantId sets TenantId field to given value. + + +### GetCustomerId + +`func (o *TagResponse1) GetCustomerId() string` + +GetCustomerId returns the CustomerId field if non-nil, zero value otherwise. + +### GetCustomerIdOk + +`func (o *TagResponse1) GetCustomerIdOk() (*string, bool)` + +GetCustomerIdOk returns a tuple with the CustomerId field if it's non-nil, zero value otherwise +and a boolean to check if the value has been set. + +### SetCustomerId + +`func (o *TagResponse1) SetCustomerId(v string)` + +SetCustomerId sets CustomerId field to given value. + + ### GetTagId `func (o *TagResponse1) GetTagId() float32` @@ -46,24 +89,44 @@ and a boolean to check if the value has been set. SetTagId sets TagId field to given value. -### GetTagName +### GetName + +`func (o *TagResponse1) GetName() string` + +GetName returns the Name field if non-nil, zero value otherwise. + +### GetNameOk + +`func (o *TagResponse1) GetNameOk() (*string, bool)` + +GetNameOk returns a tuple with the Name field if it's non-nil, zero value otherwise +and a boolean to check if the value has been set. + +### SetName + +`func (o *TagResponse1) SetName(v string)` + +SetName sets Name field to given value. + + +### GetColor -`func (o *TagResponse1) GetTagName() string` +`func (o *TagResponse1) GetColor() string` -GetTagName returns the TagName field if non-nil, zero value otherwise. +GetColor returns the Color field if non-nil, zero value otherwise. -### GetTagNameOk +### GetColorOk -`func (o *TagResponse1) GetTagNameOk() (*string, bool)` +`func (o *TagResponse1) GetColorOk() (*string, bool)` -GetTagNameOk returns a tuple with the TagName field if it's non-nil, zero value otherwise +GetColorOk returns a tuple with the Color field if it's non-nil, zero value otherwise and a boolean to check if the value has been set. -### SetTagName +### SetColor -`func (o *TagResponse1) SetTagName(v string)` +`func (o *TagResponse1) SetColor(v string)` -SetTagName sets TagName field to given value. +SetColor sets Color field to given value. diff --git a/openapi/model_add_on_quantity_request.go b/openapi/model_add_on_quantity_request.go index 33c4e19..e51a155 100644 --- a/openapi/model_add_on_quantity_request.go +++ b/openapi/model_add_on_quantity_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_add_on_request.go b/openapi/model_add_on_request.go index 78338e8..9a1e62b 100644 --- a/openapi/model_add_on_request.go +++ b/openapi/model_add_on_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_add_on_response.go b/openapi/model_add_on_response.go index 195d04f..9c520c6 100644 --- a/openapi/model_add_on_response.go +++ b/openapi/model_add_on_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_additional_ip.go b/openapi/model_additional_ip.go index 9757220..3c47da7 100644 --- a/openapi/model_additional_ip.go +++ b/openapi/model_additional_ip.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_api_permissions_response.go b/openapi/model_api_permissions_response.go index 5f7a0a6..5c727cb 100644 --- a/openapi/model_api_permissions_response.go +++ b/openapi/model_api_permissions_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_application_config.go b/openapi/model_application_config.go index 29561f7..e34d07b 100644 --- a/openapi/model_application_config.go +++ b/openapi/model_application_config.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_application_requirements.go b/openapi/model_application_requirements.go index ada556d..56ba2a5 100644 --- a/openapi/model_application_requirements.go +++ b/openapi/model_application_requirements.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_application_response.go b/openapi/model_application_response.go index 4a1ed88..7385c10 100644 --- a/openapi/model_application_response.go +++ b/openapi/model_application_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_assign_instance_private_network_response.go b/openapi/model_assign_instance_private_network_response.go index 4db536d..fdd29f8 100644 --- a/openapi/model_assign_instance_private_network_response.go +++ b/openapi/model_assign_instance_private_network_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_assignment_audit_response.go b/openapi/model_assignment_audit_response.go index d9f5191..f8473bc 100644 --- a/openapi/model_assignment_audit_response.go +++ b/openapi/model_assignment_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_assignment_response.go b/openapi/model_assignment_response.go index ff7c1b1..f505d6e 100644 --- a/openapi/model_assignment_response.go +++ b/openapi/model_assignment_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_auto_scaling_type_request.go b/openapi/model_auto_scaling_type_request.go index 8895aa1..676cef9 100644 --- a/openapi/model_auto_scaling_type_request.go +++ b/openapi/model_auto_scaling_type_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_auto_scaling_type_response.go b/openapi/model_auto_scaling_type_response.go index e3ee22f..4913cee 100644 --- a/openapi/model_auto_scaling_type_response.go +++ b/openapi/model_auto_scaling_type_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_cancel_instance_response.go b/openapi/model_cancel_instance_response.go index a450bc3..b274d48 100644 --- a/openapi/model_cancel_instance_response.go +++ b/openapi/model_cancel_instance_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_cancel_instance_response_data.go b/openapi/model_cancel_instance_response_data.go index b7c3072..7a0c1b0 100644 --- a/openapi/model_cancel_instance_response_data.go +++ b/openapi/model_cancel_instance_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_cancel_object_storage_response.go b/openapi/model_cancel_object_storage_response.go index 2db8152..60879c2 100644 --- a/openapi/model_cancel_object_storage_response.go +++ b/openapi/model_cancel_object_storage_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_cancel_object_storage_response_data.go b/openapi/model_cancel_object_storage_response_data.go index bdd6cac..64baae5 100644 --- a/openapi/model_cancel_object_storage_response_data.go +++ b/openapi/model_cancel_object_storage_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_client_response.go b/openapi/model_client_response.go index 08d614f..74025fc 100644 --- a/openapi/model_client_response.go +++ b/openapi/model_client_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_client_secret_response.go b/openapi/model_client_secret_response.go index ca6dfc6..c81dc8f 100644 --- a/openapi/model_client_secret_response.go +++ b/openapi/model_client_secret_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_assignment_response.go b/openapi/model_create_assignment_response.go index acc594a..30eafc4 100644 --- a/openapi/model_create_assignment_response.go +++ b/openapi/model_create_assignment_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_custom_image_fail_response.go b/openapi/model_create_custom_image_fail_response.go index af1615f..b5ed6e8 100644 --- a/openapi/model_create_custom_image_fail_response.go +++ b/openapi/model_create_custom_image_fail_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_custom_image_request.go b/openapi/model_create_custom_image_request.go index 892e33b..c5a2f80 100644 --- a/openapi/model_create_custom_image_request.go +++ b/openapi/model_create_custom_image_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_custom_image_response.go b/openapi/model_create_custom_image_response.go index 5c7482d..43a02f6 100644 --- a/openapi/model_create_custom_image_response.go +++ b/openapi/model_create_custom_image_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_custom_image_response_data.go b/openapi/model_create_custom_image_response_data.go index 7846d3b..223eb42 100644 --- a/openapi/model_create_custom_image_response_data.go +++ b/openapi/model_create_custom_image_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_instance_addons.go b/openapi/model_create_instance_addons.go index 3d13993..c204f81 100644 --- a/openapi/model_create_instance_addons.go +++ b/openapi/model_create_instance_addons.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_instance_request.go b/openapi/model_create_instance_request.go index 32e7176..b663407 100644 --- a/openapi/model_create_instance_request.go +++ b/openapi/model_create_instance_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_instance_response.go b/openapi/model_create_instance_response.go index 67b78bc..4264c07 100644 --- a/openapi/model_create_instance_response.go +++ b/openapi/model_create_instance_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_instance_response_data.go b/openapi/model_create_instance_response_data.go index 2a42358..4b870ee 100644 --- a/openapi/model_create_instance_response_data.go +++ b/openapi/model_create_instance_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_object_storage_request.go b/openapi/model_create_object_storage_request.go index f04112f..d4dad81 100644 --- a/openapi/model_create_object_storage_request.go +++ b/openapi/model_create_object_storage_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_object_storage_response.go b/openapi/model_create_object_storage_response.go index be9e427..5d1543f 100644 --- a/openapi/model_create_object_storage_response.go +++ b/openapi/model_create_object_storage_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_object_storage_response_data.go b/openapi/model_create_object_storage_response_data.go index 08532f5..ed25e2e 100644 --- a/openapi/model_create_object_storage_response_data.go +++ b/openapi/model_create_object_storage_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_private_network_request.go b/openapi/model_create_private_network_request.go index 34b09d2..fb846bf 100644 --- a/openapi/model_create_private_network_request.go +++ b/openapi/model_create_private_network_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_private_network_response.go b/openapi/model_create_private_network_response.go index ce3a881..7d25bd6 100644 --- a/openapi/model_create_private_network_response.go +++ b/openapi/model_create_private_network_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_role_request.go b/openapi/model_create_role_request.go index 9700fd8..b9ffe24 100644 --- a/openapi/model_create_role_request.go +++ b/openapi/model_create_role_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_role_response.go b/openapi/model_create_role_response.go index d0dd3c6..e61ea80 100644 --- a/openapi/model_create_role_response.go +++ b/openapi/model_create_role_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_role_response_data.go b/openapi/model_create_role_response_data.go index d1b68a3..4b68084 100644 --- a/openapi/model_create_role_response_data.go +++ b/openapi/model_create_role_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_secret_request.go b/openapi/model_create_secret_request.go index 30a9214..e3d03e7 100644 --- a/openapi/model_create_secret_request.go +++ b/openapi/model_create_secret_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_secret_response.go b/openapi/model_create_secret_response.go index 7f80ec4..20dee0a 100644 --- a/openapi/model_create_secret_response.go +++ b/openapi/model_create_secret_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_snapshot_request.go b/openapi/model_create_snapshot_request.go index f5ae4d9..9a419a8 100644 --- a/openapi/model_create_snapshot_request.go +++ b/openapi/model_create_snapshot_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_snapshot_response.go b/openapi/model_create_snapshot_response.go index 96727d8..02559e3 100644 --- a/openapi/model_create_snapshot_response.go +++ b/openapi/model_create_snapshot_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_tag_request.go b/openapi/model_create_tag_request.go index 1049423..f0e7f7f 100644 --- a/openapi/model_create_tag_request.go +++ b/openapi/model_create_tag_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_tag_response.go b/openapi/model_create_tag_response.go index a5107f8..b805312 100644 --- a/openapi/model_create_tag_response.go +++ b/openapi/model_create_tag_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_tag_response_data.go b/openapi/model_create_tag_response_data.go index d5d579a..e215063 100644 --- a/openapi/model_create_tag_response_data.go +++ b/openapi/model_create_tag_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_ticket_request.go b/openapi/model_create_ticket_request.go index 855f306..13dcd21 100644 --- a/openapi/model_create_ticket_request.go +++ b/openapi/model_create_ticket_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_ticket_response.go b/openapi/model_create_ticket_response.go index b279a01..9af713d 100644 --- a/openapi/model_create_ticket_response.go +++ b/openapi/model_create_ticket_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_ticket_response_data.go b/openapi/model_create_ticket_response_data.go index 2cdfbe9..4891edf 100644 --- a/openapi/model_create_ticket_response_data.go +++ b/openapi/model_create_ticket_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_user_request.go b/openapi/model_create_user_request.go index 81568b3..9da42ee 100644 --- a/openapi/model_create_user_request.go +++ b/openapi/model_create_user_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_user_response.go b/openapi/model_create_user_response.go index bb50b15..3b54d30 100644 --- a/openapi/model_create_user_response.go +++ b/openapi/model_create_user_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_create_user_response_data.go b/openapi/model_create_user_response_data.go index 2623b4a..a846108 100644 --- a/openapi/model_create_user_response_data.go +++ b/openapi/model_create_user_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_credential_data.go b/openapi/model_credential_data.go index 6f7edaa..69c178d 100644 --- a/openapi/model_credential_data.go +++ b/openapi/model_credential_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_custom_images_stats_response.go b/openapi/model_custom_images_stats_response.go index 4e24db4..9d58184 100644 --- a/openapi/model_custom_images_stats_response.go +++ b/openapi/model_custom_images_stats_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_custom_images_stats_response_data.go b/openapi/model_custom_images_stats_response_data.go index 99e31df..3272336 100644 --- a/openapi/model_custom_images_stats_response_data.go +++ b/openapi/model_custom_images_stats_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_data_center_response.go b/openapi/model_data_center_response.go index 38e8865..3097a3c 100644 --- a/openapi/model_data_center_response.go +++ b/openapi/model_data_center_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_extra_storage_request.go b/openapi/model_extra_storage_request.go index bf18d80..85deeb7 100644 --- a/openapi/model_extra_storage_request.go +++ b/openapi/model_extra_storage_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_assignment_response.go b/openapi/model_find_assignment_response.go index 8920ce6..aea3ae4 100644 --- a/openapi/model_find_assignment_response.go +++ b/openapi/model_find_assignment_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_client_response.go b/openapi/model_find_client_response.go index f8bb858..f625ad1 100644 --- a/openapi/model_find_client_response.go +++ b/openapi/model_find_client_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_credential_response.go b/openapi/model_find_credential_response.go index 7c4c781..d570fd9 100644 --- a/openapi/model_find_credential_response.go +++ b/openapi/model_find_credential_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_image_response.go b/openapi/model_find_image_response.go index 259c571..e9b8a78 100644 --- a/openapi/model_find_image_response.go +++ b/openapi/model_find_image_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_instance_response.go b/openapi/model_find_instance_response.go index 8c420d7..518122f 100644 --- a/openapi/model_find_instance_response.go +++ b/openapi/model_find_instance_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_object_storage_response.go b/openapi/model_find_object_storage_response.go index 700a126..2bd4f6c 100644 --- a/openapi/model_find_object_storage_response.go +++ b/openapi/model_find_object_storage_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_private_network_response.go b/openapi/model_find_private_network_response.go index 371ad4e..1dc770d 100644 --- a/openapi/model_find_private_network_response.go +++ b/openapi/model_find_private_network_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_role_response.go b/openapi/model_find_role_response.go index b3c28f2..924b824 100644 --- a/openapi/model_find_role_response.go +++ b/openapi/model_find_role_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_secret_response.go b/openapi/model_find_secret_response.go index b072a49..8bcf634 100644 --- a/openapi/model_find_secret_response.go +++ b/openapi/model_find_secret_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_snapshot_response.go b/openapi/model_find_snapshot_response.go index bfa2ac6..4d81561 100644 --- a/openapi/model_find_snapshot_response.go +++ b/openapi/model_find_snapshot_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_tag_response.go b/openapi/model_find_tag_response.go index 8a14a65..9afe4b8 100644 --- a/openapi/model_find_tag_response.go +++ b/openapi/model_find_tag_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -17,7 +17,7 @@ import ( // FindTagResponse struct for FindTagResponse type FindTagResponse struct { - Data []TagResponse `json:"data"` + Data []TagResponse1 `json:"data"` Links SelfLinks `json:"_links"` } @@ -25,7 +25,7 @@ type FindTagResponse struct { // This constructor will assign default values to properties that have it defined, // and makes sure properties required by API are set, but the set of arguments // will change when the set of required properties is changed -func NewFindTagResponse(data []TagResponse, links SelfLinks) *FindTagResponse { +func NewFindTagResponse(data []TagResponse1, links SelfLinks) *FindTagResponse { this := FindTagResponse{} this.Data = data this.Links = links @@ -41,9 +41,9 @@ func NewFindTagResponseWithDefaults() *FindTagResponse { } // GetData returns the Data field value -func (o *FindTagResponse) GetData() []TagResponse { +func (o *FindTagResponse) GetData() []TagResponse1 { if o == nil { - var ret []TagResponse + var ret []TagResponse1 return ret } @@ -52,7 +52,7 @@ func (o *FindTagResponse) GetData() []TagResponse { // GetDataOk returns a tuple with the Data field value // and a boolean to check if the value has been set. -func (o *FindTagResponse) GetDataOk() (*[]TagResponse, bool) { +func (o *FindTagResponse) GetDataOk() (*[]TagResponse1, bool) { if o == nil { return nil, false } @@ -60,7 +60,7 @@ func (o *FindTagResponse) GetDataOk() (*[]TagResponse, bool) { } // SetData sets field value -func (o *FindTagResponse) SetData(v []TagResponse) { +func (o *FindTagResponse) SetData(v []TagResponse1) { o.Data = v } diff --git a/openapi/model_find_user_is_password_set_response.go b/openapi/model_find_user_is_password_set_response.go index 32b2d6b..e9f5148 100644 --- a/openapi/model_find_user_is_password_set_response.go +++ b/openapi/model_find_user_is_password_set_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_user_response.go b/openapi/model_find_user_response.go index eee93ba..3b9a35f 100644 --- a/openapi/model_find_user_response.go +++ b/openapi/model_find_user_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_find_vnc_response.go b/openapi/model_find_vnc_response.go index 260f830..a5f8dce 100644 --- a/openapi/model_find_vnc_response.go +++ b/openapi/model_find_vnc_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_firewalling_upgrade_request.go b/openapi/model_firewalling_upgrade_request.go index 6703418..06ad6ed 100644 --- a/openapi/model_firewalling_upgrade_request.go +++ b/openapi/model_firewalling_upgrade_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_generate_client_secret_response.go b/openapi/model_generate_client_secret_response.go index 49d4d9f..d0be120 100644 --- a/openapi/model_generate_client_secret_response.go +++ b/openapi/model_generate_client_secret_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_image_audit_response.go b/openapi/model_image_audit_response.go index a87f1fe..e9cf17d 100644 --- a/openapi/model_image_audit_response.go +++ b/openapi/model_image_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_image_audit_response_data.go b/openapi/model_image_audit_response_data.go index cd0554d..a6b4083 100644 --- a/openapi/model_image_audit_response_data.go +++ b/openapi/model_image_audit_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_image_response.go b/openapi/model_image_response.go index 6534589..9b54174 100644 --- a/openapi/model_image_response.go +++ b/openapi/model_image_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_assignment_self_links.go b/openapi/model_instance_assignment_self_links.go index d50f4d3..859f422 100644 --- a/openapi/model_instance_assignment_self_links.go +++ b/openapi/model_instance_assignment_self_links.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_rescue_action_response.go b/openapi/model_instance_rescue_action_response.go index a8f4344..8e166ef 100644 --- a/openapi/model_instance_rescue_action_response.go +++ b/openapi/model_instance_rescue_action_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_rescue_action_response_data.go b/openapi/model_instance_rescue_action_response_data.go index 932915f..e75c41c 100644 --- a/openapi/model_instance_rescue_action_response_data.go +++ b/openapi/model_instance_rescue_action_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_reset_password_action_response.go b/openapi/model_instance_reset_password_action_response.go index 5988cba..a436961 100644 --- a/openapi/model_instance_reset_password_action_response.go +++ b/openapi/model_instance_reset_password_action_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_reset_password_action_response_data.go b/openapi/model_instance_reset_password_action_response_data.go index 5e25cd5..b03ceab 100644 --- a/openapi/model_instance_reset_password_action_response_data.go +++ b/openapi/model_instance_reset_password_action_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_response.go b/openapi/model_instance_response.go index 6daec40..e7863e4 100644 --- a/openapi/model_instance_response.go +++ b/openapi/model_instance_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -59,6 +59,10 @@ type InstanceResponse struct { Status InstanceStatus `json:"status"` // ID of host system VHostId int64 `json:"vHostId"` + // Number of host system + VHostNumber int64 `json:"vHostNumber"` + // Name of host system + VHostName string `json:"vHostName"` AddOns []AddOnResponse `json:"addOns"` // Message in case of an error. ErrorMessage *string `json:"errorMessage,omitempty"` @@ -74,7 +78,7 @@ type InstanceResponse struct { // This constructor will assign default values to properties that have it defined, // and makes sure properties required by API are set, but the set of arguments // will change when the set of required properties is changed -func NewInstanceResponse(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, addOns []AddOnResponse, productType string, productName string) *InstanceResponse { +func NewInstanceResponse(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, vHostNumber int64, vHostName string, addOns []AddOnResponse, productType string, productName string) *InstanceResponse { this := InstanceResponse{} this.TenantId = tenantId this.CustomerId = customerId @@ -98,6 +102,8 @@ func NewInstanceResponse(tenantId string, customerId string, additionalIps []Add this.CancelDate = cancelDate this.Status = status this.VHostId = vHostId + this.VHostNumber = vHostNumber + this.VHostName = vHostName this.AddOns = addOns this.ProductType = productType this.ProductName = productName @@ -640,6 +646,54 @@ func (o *InstanceResponse) SetVHostId(v int64) { o.VHostId = v } +// GetVHostNumber returns the VHostNumber field value +func (o *InstanceResponse) GetVHostNumber() int64 { + if o == nil { + var ret int64 + return ret + } + + return o.VHostNumber +} + +// GetVHostNumberOk returns a tuple with the VHostNumber field value +// and a boolean to check if the value has been set. +func (o *InstanceResponse) GetVHostNumberOk() (*int64, bool) { + if o == nil { + return nil, false + } + return &o.VHostNumber, true +} + +// SetVHostNumber sets field value +func (o *InstanceResponse) SetVHostNumber(v int64) { + o.VHostNumber = v +} + +// GetVHostName returns the VHostName field value +func (o *InstanceResponse) GetVHostName() string { + if o == nil { + var ret string + return ret + } + + return o.VHostName +} + +// GetVHostNameOk returns a tuple with the VHostName field value +// and a boolean to check if the value has been set. +func (o *InstanceResponse) GetVHostNameOk() (*string, bool) { + if o == nil { + return nil, false + } + return &o.VHostName, true +} + +// SetVHostName sets field value +func (o *InstanceResponse) SetVHostName(v string) { + o.VHostName = v +} + // GetAddOns returns the AddOns field value func (o *InstanceResponse) GetAddOns() []AddOnResponse { if o == nil { @@ -844,6 +898,12 @@ func (o InstanceResponse) MarshalJSON() ([]byte, error) { if true { toSerialize["vHostId"] = o.VHostId } + if true { + toSerialize["vHostNumber"] = o.VHostNumber + } + if true { + toSerialize["vHostName"] = o.VHostName + } if true { toSerialize["addOns"] = o.AddOns } diff --git a/openapi/model_instance_restart_action_response.go b/openapi/model_instance_restart_action_response.go index 03082b3..7e63c71 100644 --- a/openapi/model_instance_restart_action_response.go +++ b/openapi/model_instance_restart_action_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_restart_action_response_data.go b/openapi/model_instance_restart_action_response_data.go index 7a13b8c..07053fd 100644 --- a/openapi/model_instance_restart_action_response_data.go +++ b/openapi/model_instance_restart_action_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_shutdown_action_response.go b/openapi/model_instance_shutdown_action_response.go index 496ab56..eb60bba 100644 --- a/openapi/model_instance_shutdown_action_response.go +++ b/openapi/model_instance_shutdown_action_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_shutdown_action_response_data.go b/openapi/model_instance_shutdown_action_response_data.go index c21bd3e..dd9165c 100644 --- a/openapi/model_instance_shutdown_action_response_data.go +++ b/openapi/model_instance_shutdown_action_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_start_action_response.go b/openapi/model_instance_start_action_response.go index afdb9f4..d05daf1 100644 --- a/openapi/model_instance_start_action_response.go +++ b/openapi/model_instance_start_action_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_start_action_response_data.go b/openapi/model_instance_start_action_response_data.go index be4fd92..f37355a 100644 --- a/openapi/model_instance_start_action_response_data.go +++ b/openapi/model_instance_start_action_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_status.go b/openapi/model_instance_status.go index d960157..3d871ba 100644 --- a/openapi/model_instance_status.go +++ b/openapi/model_instance_status.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_stop_action_response.go b/openapi/model_instance_stop_action_response.go index 5ec47fb..e8b0388 100644 --- a/openapi/model_instance_stop_action_response.go +++ b/openapi/model_instance_stop_action_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instance_stop_action_response_data.go b/openapi/model_instance_stop_action_response_data.go index 16d8ceb..88e05e4 100644 --- a/openapi/model_instance_stop_action_response_data.go +++ b/openapi/model_instance_stop_action_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instances.go b/openapi/model_instances.go index d0f2b20..3289d19 100644 --- a/openapi/model_instances.go +++ b/openapi/model_instances.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instances_actions_audit_response.go b/openapi/model_instances_actions_audit_response.go index aa4f814..f1a4a5a 100644 --- a/openapi/model_instances_actions_audit_response.go +++ b/openapi/model_instances_actions_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instances_actions_rescue_request.go b/openapi/model_instances_actions_rescue_request.go index d40e5bb..fa90db2 100644 --- a/openapi/model_instances_actions_rescue_request.go +++ b/openapi/model_instances_actions_rescue_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instances_audit_response.go b/openapi/model_instances_audit_response.go index 8ac467f..f71895c 100644 --- a/openapi/model_instances_audit_response.go +++ b/openapi/model_instances_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_instances_reset_password_actions_request.go b/openapi/model_instances_reset_password_actions_request.go index 8c576ed..d5f19cc 100644 --- a/openapi/model_instances_reset_password_actions_request.go +++ b/openapi/model_instances_reset_password_actions_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_ip_config.go b/openapi/model_ip_config.go index 777db72..8d7b1eb 100644 --- a/openapi/model_ip_config.go +++ b/openapi/model_ip_config.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_ip_v4.go b/openapi/model_ip_v4.go index fd65f39..e464b67 100644 --- a/openapi/model_ip_v4.go +++ b/openapi/model_ip_v4.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_ip_v6.go b/openapi/model_ip_v6.go index a801b22..7c0e3cb 100644 --- a/openapi/model_ip_v6.go +++ b/openapi/model_ip_v6.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_links.go b/openapi/model_links.go index faa47a5..b9a021b 100644 --- a/openapi/model_links.go +++ b/openapi/model_links.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_api_permission_response.go b/openapi/model_list_api_permission_response.go index 52d15f2..c1e3226 100644 --- a/openapi/model_list_api_permission_response.go +++ b/openapi/model_list_api_permission_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_applications_response.go b/openapi/model_list_applications_response.go index a7adf23..3b0dccb 100644 --- a/openapi/model_list_applications_response.go +++ b/openapi/model_list_applications_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_assignment_audits_response.go b/openapi/model_list_assignment_audits_response.go index 41755e1..323f5eb 100644 --- a/openapi/model_list_assignment_audits_response.go +++ b/openapi/model_list_assignment_audits_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_assignment_response.go b/openapi/model_list_assignment_response.go index 663b0da..aa99ae9 100644 --- a/openapi/model_list_assignment_response.go +++ b/openapi/model_list_assignment_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_credential_response.go b/openapi/model_list_credential_response.go index 03604f7..491c168 100644 --- a/openapi/model_list_credential_response.go +++ b/openapi/model_list_credential_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_data_center_response.go b/openapi/model_list_data_center_response.go index bbb5a24..42866c7 100644 --- a/openapi/model_list_data_center_response.go +++ b/openapi/model_list_data_center_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_image_response.go b/openapi/model_list_image_response.go index 97ded90..aff674e 100644 --- a/openapi/model_list_image_response.go +++ b/openapi/model_list_image_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_image_response_data.go b/openapi/model_list_image_response_data.go index 4c3405d..132c8e0 100644 --- a/openapi/model_list_image_response_data.go +++ b/openapi/model_list_image_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -51,14 +51,14 @@ type ListImageResponseData struct { // The last modified date time for the image LastModifiedDate time.Time `json:"lastModifiedDate"` // The tags assigned to the image - Tags []TagResponse1 `json:"tags"` + Tags []TagResponse `json:"tags"` } // NewListImageResponseData instantiates a new ListImageResponseData object // This constructor will assign default values to properties that have it defined, // and makes sure properties required by API are set, but the set of arguments // will change when the set of required properties is changed -func NewListImageResponseData(imageId string, tenantId string, customerId string, name string, description string, url string, sizeMb float32, uploadedSizeMb float32, osType string, version string, format string, status string, errorMessage string, standardImage bool, creationDate time.Time, lastModifiedDate time.Time, tags []TagResponse1) *ListImageResponseData { +func NewListImageResponseData(imageId string, tenantId string, customerId string, name string, description string, url string, sizeMb float32, uploadedSizeMb float32, osType string, version string, format string, status string, errorMessage string, standardImage bool, creationDate time.Time, lastModifiedDate time.Time, tags []TagResponse) *ListImageResponseData { this := ListImageResponseData{} this.ImageId = imageId this.TenantId = tenantId @@ -473,9 +473,9 @@ func (o *ListImageResponseData) SetLastModifiedDate(v time.Time) { } // GetTags returns the Tags field value -func (o *ListImageResponseData) GetTags() []TagResponse1 { +func (o *ListImageResponseData) GetTags() []TagResponse { if o == nil { - var ret []TagResponse1 + var ret []TagResponse return ret } @@ -484,7 +484,7 @@ func (o *ListImageResponseData) GetTags() []TagResponse1 { // GetTagsOk returns a tuple with the Tags field value // and a boolean to check if the value has been set. -func (o *ListImageResponseData) GetTagsOk() (*[]TagResponse1, bool) { +func (o *ListImageResponseData) GetTagsOk() (*[]TagResponse, bool) { if o == nil { return nil, false } @@ -492,7 +492,7 @@ func (o *ListImageResponseData) GetTagsOk() (*[]TagResponse1, bool) { } // SetTags sets field value -func (o *ListImageResponseData) SetTags(v []TagResponse1) { +func (o *ListImageResponseData) SetTags(v []TagResponse) { o.Tags = v } diff --git a/openapi/model_list_instances_actions_audit_response.go b/openapi/model_list_instances_actions_audit_response.go index 59293c9..dd64f7c 100644 --- a/openapi/model_list_instances_actions_audit_response.go +++ b/openapi/model_list_instances_actions_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_instances_audit_response.go b/openapi/model_list_instances_audit_response.go index d69e870..f199acf 100644 --- a/openapi/model_list_instances_audit_response.go +++ b/openapi/model_list_instances_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_instances_response.go b/openapi/model_list_instances_response.go index c541b34..18ad5d6 100644 --- a/openapi/model_list_instances_response.go +++ b/openapi/model_list_instances_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_instances_response_data.go b/openapi/model_list_instances_response_data.go index d0e2d71..bc4eb5e 100644 --- a/openapi/model_list_instances_response_data.go +++ b/openapi/model_list_instances_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -59,6 +59,10 @@ type ListInstancesResponseData struct { Status InstanceStatus `json:"status"` // ID of host system VHostId int64 `json:"vHostId"` + // Number of host system + VHostNumber int64 `json:"vHostNumber"` + // Name of host system + VHostName string `json:"vHostName"` AddOns []AddOnResponse `json:"addOns"` // Message in case of an error. ErrorMessage *string `json:"errorMessage,omitempty"` @@ -74,7 +78,7 @@ type ListInstancesResponseData struct { // This constructor will assign default values to properties that have it defined, // and makes sure properties required by API are set, but the set of arguments // will change when the set of required properties is changed -func NewListInstancesResponseData(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, addOns []AddOnResponse, productType string, productName string) *ListInstancesResponseData { +func NewListInstancesResponseData(tenantId string, customerId string, additionalIps []AdditionalIp, name string, displayName string, instanceId int64, dataCenter string, region string, regionName string, productId string, imageId string, ipConfig IpConfig, macAddress string, ramMb float32, cpuCores int64, osType string, diskMb float32, sshKeys []int64, createdDate time.Time, cancelDate string, status InstanceStatus, vHostId int64, vHostNumber int64, vHostName string, addOns []AddOnResponse, productType string, productName string) *ListInstancesResponseData { this := ListInstancesResponseData{} this.TenantId = tenantId this.CustomerId = customerId @@ -98,6 +102,8 @@ func NewListInstancesResponseData(tenantId string, customerId string, additional this.CancelDate = cancelDate this.Status = status this.VHostId = vHostId + this.VHostNumber = vHostNumber + this.VHostName = vHostName this.AddOns = addOns this.ProductType = productType this.ProductName = productName @@ -640,6 +646,54 @@ func (o *ListInstancesResponseData) SetVHostId(v int64) { o.VHostId = v } +// GetVHostNumber returns the VHostNumber field value +func (o *ListInstancesResponseData) GetVHostNumber() int64 { + if o == nil { + var ret int64 + return ret + } + + return o.VHostNumber +} + +// GetVHostNumberOk returns a tuple with the VHostNumber field value +// and a boolean to check if the value has been set. +func (o *ListInstancesResponseData) GetVHostNumberOk() (*int64, bool) { + if o == nil { + return nil, false + } + return &o.VHostNumber, true +} + +// SetVHostNumber sets field value +func (o *ListInstancesResponseData) SetVHostNumber(v int64) { + o.VHostNumber = v +} + +// GetVHostName returns the VHostName field value +func (o *ListInstancesResponseData) GetVHostName() string { + if o == nil { + var ret string + return ret + } + + return o.VHostName +} + +// GetVHostNameOk returns a tuple with the VHostName field value +// and a boolean to check if the value has been set. +func (o *ListInstancesResponseData) GetVHostNameOk() (*string, bool) { + if o == nil { + return nil, false + } + return &o.VHostName, true +} + +// SetVHostName sets field value +func (o *ListInstancesResponseData) SetVHostName(v string) { + o.VHostName = v +} + // GetAddOns returns the AddOns field value func (o *ListInstancesResponseData) GetAddOns() []AddOnResponse { if o == nil { @@ -844,6 +898,12 @@ func (o ListInstancesResponseData) MarshalJSON() ([]byte, error) { if true { toSerialize["vHostId"] = o.VHostId } + if true { + toSerialize["vHostNumber"] = o.VHostNumber + } + if true { + toSerialize["vHostName"] = o.VHostName + } if true { toSerialize["addOns"] = o.AddOns } diff --git a/openapi/model_list_object_storage_audit_response.go b/openapi/model_list_object_storage_audit_response.go index 0bd5efe..553ccef 100644 --- a/openapi/model_list_object_storage_audit_response.go +++ b/openapi/model_list_object_storage_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_object_storage_response.go b/openapi/model_list_object_storage_response.go index 6e53e38..bb15cb6 100644 --- a/openapi/model_list_object_storage_response.go +++ b/openapi/model_list_object_storage_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_private_network_audit_response.go b/openapi/model_list_private_network_audit_response.go index 2da774d..1438f8b 100644 --- a/openapi/model_list_private_network_audit_response.go +++ b/openapi/model_list_private_network_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_private_network_response.go b/openapi/model_list_private_network_response.go index f8ea0e8..7e46250 100644 --- a/openapi/model_list_private_network_response.go +++ b/openapi/model_list_private_network_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_private_network_response_data.go b/openapi/model_list_private_network_response_data.go index f5f3980..3a89062 100644 --- a/openapi/model_list_private_network_response_data.go +++ b/openapi/model_list_private_network_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_role_audit_response.go b/openapi/model_list_role_audit_response.go index fe24516..aa2e4d0 100644 --- a/openapi/model_list_role_audit_response.go +++ b/openapi/model_list_role_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_role_response.go b/openapi/model_list_role_response.go index ff148c4..958d5aa 100644 --- a/openapi/model_list_role_response.go +++ b/openapi/model_list_role_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_secret_audit_response.go b/openapi/model_list_secret_audit_response.go index df147b3..3968b53 100644 --- a/openapi/model_list_secret_audit_response.go +++ b/openapi/model_list_secret_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_secret_response.go b/openapi/model_list_secret_response.go index 7e032b4..15b6c41 100644 --- a/openapi/model_list_secret_response.go +++ b/openapi/model_list_secret_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_snapshot_response.go b/openapi/model_list_snapshot_response.go index 849aa5b..49f632b 100644 --- a/openapi/model_list_snapshot_response.go +++ b/openapi/model_list_snapshot_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_snapshots_audit_response.go b/openapi/model_list_snapshots_audit_response.go index 2408a03..b6e885c 100644 --- a/openapi/model_list_snapshots_audit_response.go +++ b/openapi/model_list_snapshots_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_tag_audits_response.go b/openapi/model_list_tag_audits_response.go index 5c77a19..8e4ffe2 100644 --- a/openapi/model_list_tag_audits_response.go +++ b/openapi/model_list_tag_audits_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_tag_response.go b/openapi/model_list_tag_response.go index f02347c..f4225d1 100644 --- a/openapi/model_list_tag_response.go +++ b/openapi/model_list_tag_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -19,7 +19,7 @@ import ( type ListTagResponse struct { // Data about pagination like how many results, pages, page size. Pagination PaginationMeta `json:"_pagination"` - Data []TagResponse `json:"data"` + Data []TagResponse1 `json:"data"` Links Links `json:"_links"` } @@ -27,7 +27,7 @@ type ListTagResponse struct { // This constructor will assign default values to properties that have it defined, // and makes sure properties required by API are set, but the set of arguments // will change when the set of required properties is changed -func NewListTagResponse(pagination PaginationMeta, data []TagResponse, links Links) *ListTagResponse { +func NewListTagResponse(pagination PaginationMeta, data []TagResponse1, links Links) *ListTagResponse { this := ListTagResponse{} this.Pagination = pagination this.Data = data @@ -68,9 +68,9 @@ func (o *ListTagResponse) SetPagination(v PaginationMeta) { } // GetData returns the Data field value -func (o *ListTagResponse) GetData() []TagResponse { +func (o *ListTagResponse) GetData() []TagResponse1 { if o == nil { - var ret []TagResponse + var ret []TagResponse1 return ret } @@ -79,7 +79,7 @@ func (o *ListTagResponse) GetData() []TagResponse { // GetDataOk returns a tuple with the Data field value // and a boolean to check if the value has been set. -func (o *ListTagResponse) GetDataOk() (*[]TagResponse, bool) { +func (o *ListTagResponse) GetDataOk() (*[]TagResponse1, bool) { if o == nil { return nil, false } @@ -87,7 +87,7 @@ func (o *ListTagResponse) GetDataOk() (*[]TagResponse, bool) { } // SetData sets field value -func (o *ListTagResponse) SetData(v []TagResponse) { +func (o *ListTagResponse) SetData(v []TagResponse1) { o.Data = v } diff --git a/openapi/model_list_ticket_metadata_response.go b/openapi/model_list_ticket_metadata_response.go index bc04943..c859f5a 100644 --- a/openapi/model_list_ticket_metadata_response.go +++ b/openapi/model_list_ticket_metadata_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_user_audit_response.go b/openapi/model_list_user_audit_response.go index b0d1639..059e6ec 100644 --- a/openapi/model_list_user_audit_response.go +++ b/openapi/model_list_user_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_list_user_response.go b/openapi/model_list_user_response.go index cbaae3a..5e1f63d 100644 --- a/openapi/model_list_user_response.go +++ b/openapi/model_list_user_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_metadata_type.go b/openapi/model_metadata_type.go index 63eadec..eb55a34 100644 --- a/openapi/model_metadata_type.go +++ b/openapi/model_metadata_type.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_minimum_requirements.go b/openapi/model_minimum_requirements.go index 7535e24..bebcf37 100644 --- a/openapi/model_minimum_requirements.go +++ b/openapi/model_minimum_requirements.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_object_storage_audit_response.go b/openapi/model_object_storage_audit_response.go index 690835f..a98a71c 100644 --- a/openapi/model_object_storage_audit_response.go +++ b/openapi/model_object_storage_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_object_storage_response.go b/openapi/model_object_storage_response.go index e3ab8f7..3a5ddee 100644 --- a/openapi/model_object_storage_response.go +++ b/openapi/model_object_storage_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_object_storages_stats_response.go b/openapi/model_object_storages_stats_response.go index 813a096..5e59c91 100644 --- a/openapi/model_object_storages_stats_response.go +++ b/openapi/model_object_storages_stats_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_object_storages_stats_response_data.go b/openapi/model_object_storages_stats_response_data.go index 03b0f45..36804bf 100644 --- a/openapi/model_object_storages_stats_response_data.go +++ b/openapi/model_object_storages_stats_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_optimal_requirements.go b/openapi/model_optimal_requirements.go index 4f8a1ea..fded030 100644 --- a/openapi/model_optimal_requirements.go +++ b/openapi/model_optimal_requirements.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_pagination_meta.go b/openapi/model_pagination_meta.go index 9323ecd..5a8edf5 100644 --- a/openapi/model_pagination_meta.go +++ b/openapi/model_pagination_meta.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_patch_instance_request.go b/openapi/model_patch_instance_request.go index 1bbe23c..1731726 100644 --- a/openapi/model_patch_instance_request.go +++ b/openapi/model_patch_instance_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -19,8 +19,6 @@ import ( type PatchInstanceRequest struct { // The display name of the instance DisplayName *string `json:"displayName,omitempty"` - // Enable/Disable the VNC option for instance - VncEnabled *bool `json:"vncEnabled,omitempty"` } // NewPatchInstanceRequest instantiates a new PatchInstanceRequest object @@ -72,46 +70,11 @@ func (o *PatchInstanceRequest) SetDisplayName(v string) { o.DisplayName = &v } -// GetVncEnabled returns the VncEnabled field value if set, zero value otherwise. -func (o *PatchInstanceRequest) GetVncEnabled() bool { - if o == nil || o.VncEnabled == nil { - var ret bool - return ret - } - return *o.VncEnabled -} - -// GetVncEnabledOk returns a tuple with the VncEnabled field value if set, nil otherwise -// and a boolean to check if the value has been set. -func (o *PatchInstanceRequest) GetVncEnabledOk() (*bool, bool) { - if o == nil || o.VncEnabled == nil { - return nil, false - } - return o.VncEnabled, true -} - -// HasVncEnabled returns a boolean if a field has been set. -func (o *PatchInstanceRequest) HasVncEnabled() bool { - if o != nil && o.VncEnabled != nil { - return true - } - - return false -} - -// SetVncEnabled gets a reference to the given bool and assigns it to the VncEnabled field. -func (o *PatchInstanceRequest) SetVncEnabled(v bool) { - o.VncEnabled = &v -} - func (o PatchInstanceRequest) MarshalJSON() ([]byte, error) { toSerialize := map[string]interface{}{} if o.DisplayName != nil { toSerialize["displayName"] = o.DisplayName } - if o.VncEnabled != nil { - toSerialize["vncEnabled"] = o.VncEnabled - } return json.Marshal(toSerialize) } diff --git a/openapi/model_patch_instance_response.go b/openapi/model_patch_instance_response.go index 707c09c..4b48b95 100644 --- a/openapi/model_patch_instance_response.go +++ b/openapi/model_patch_instance_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_patch_instance_response_data.go b/openapi/model_patch_instance_response_data.go index 4d8a027..d3cdb3a 100644 --- a/openapi/model_patch_instance_response_data.go +++ b/openapi/model_patch_instance_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_patch_object_storage_request.go b/openapi/model_patch_object_storage_request.go index 2001df6..8a85c71 100644 --- a/openapi/model_patch_object_storage_request.go +++ b/openapi/model_patch_object_storage_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_patch_private_network_request.go b/openapi/model_patch_private_network_request.go index 09d7c7e..1d116fd 100644 --- a/openapi/model_patch_private_network_request.go +++ b/openapi/model_patch_private_network_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_patch_private_network_response.go b/openapi/model_patch_private_network_response.go index 1a4d505..a06e65c 100644 --- a/openapi/model_patch_private_network_response.go +++ b/openapi/model_patch_private_network_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_patch_vnc_request.go b/openapi/model_patch_vnc_request.go index 7ee92c1..741e47f 100644 --- a/openapi/model_patch_vnc_request.go +++ b/openapi/model_patch_vnc_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_permission_request.go b/openapi/model_permission_request.go index 89f9e89..9d76bfc 100644 --- a/openapi/model_permission_request.go +++ b/openapi/model_permission_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_permission_response.go b/openapi/model_permission_response.go index c7a0a7f..74bb187 100644 --- a/openapi/model_permission_response.go +++ b/openapi/model_permission_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_private_ip_config.go b/openapi/model_private_ip_config.go index a9e2b9a..cda76fb 100644 --- a/openapi/model_private_ip_config.go +++ b/openapi/model_private_ip_config.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_private_network_audit_response.go b/openapi/model_private_network_audit_response.go index e179cd7..0088753 100644 --- a/openapi/model_private_network_audit_response.go +++ b/openapi/model_private_network_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_private_network_response.go b/openapi/model_private_network_response.go index 6d1f240..84fc6bb 100644 --- a/openapi/model_private_network_response.go +++ b/openapi/model_private_network_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_reinstall_instance_request.go b/openapi/model_reinstall_instance_request.go index 42479fe..7331a26 100644 --- a/openapi/model_reinstall_instance_request.go +++ b/openapi/model_reinstall_instance_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_reinstall_instance_response.go b/openapi/model_reinstall_instance_response.go index edf91db..32ef446 100644 --- a/openapi/model_reinstall_instance_response.go +++ b/openapi/model_reinstall_instance_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_reinstall_instance_response_data.go b/openapi/model_reinstall_instance_response_data.go index 7df0d42..8c5086c 100644 --- a/openapi/model_reinstall_instance_response_data.go +++ b/openapi/model_reinstall_instance_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_resource_permissions_response.go b/openapi/model_resource_permissions_response.go index 495b684..57c2320 100644 --- a/openapi/model_resource_permissions_response.go +++ b/openapi/model_resource_permissions_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_role_audit_response.go b/openapi/model_role_audit_response.go index 1b09c44..74819ac 100644 --- a/openapi/model_role_audit_response.go +++ b/openapi/model_role_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_role_response.go b/openapi/model_role_response.go index e28e84b..7cf12ca 100644 --- a/openapi/model_role_response.go +++ b/openapi/model_role_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_rollback_snapshot_response.go b/openapi/model_rollback_snapshot_response.go index 1c4d741..5ac2544 100644 --- a/openapi/model_rollback_snapshot_response.go +++ b/openapi/model_rollback_snapshot_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_secret_audit_response.go b/openapi/model_secret_audit_response.go index 63417c9..2216a71 100644 --- a/openapi/model_secret_audit_response.go +++ b/openapi/model_secret_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_secret_response.go b/openapi/model_secret_response.go index 1a0f8a4..7ea9192 100644 --- a/openapi/model_secret_response.go +++ b/openapi/model_secret_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_self_links.go b/openapi/model_self_links.go index 4937740..5ce6840 100644 --- a/openapi/model_self_links.go +++ b/openapi/model_self_links.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_snapshot_response.go b/openapi/model_snapshot_response.go index 6a1fa3a..cb2ba47 100644 --- a/openapi/model_snapshot_response.go +++ b/openapi/model_snapshot_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_snapshots_audit_response.go b/openapi/model_snapshots_audit_response.go index 61fdce6..a5a62d2 100644 --- a/openapi/model_snapshots_audit_response.go +++ b/openapi/model_snapshots_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_tag_assignment_self_links.go b/openapi/model_tag_assignment_self_links.go index 15259c1..2d14f12 100644 --- a/openapi/model_tag_assignment_self_links.go +++ b/openapi/model_tag_assignment_self_links.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_tag_audit_response.go b/openapi/model_tag_audit_response.go index b7b254e..eb7c897 100644 --- a/openapi/model_tag_audit_response.go +++ b/openapi/model_tag_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_tag_response.go b/openapi/model_tag_response.go index ff30dee..67cba4a 100644 --- a/openapi/model_tag_response.go +++ b/openapi/model_tag_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -17,29 +17,20 @@ import ( // TagResponse struct for TagResponse type TagResponse struct { - // Your customer tenant id - TenantId string `json:"tenantId"` - // Your customer number - CustomerId string `json:"customerId"` // Tag's id TagId float32 `json:"tagId"` // Tag's name - Name string `json:"name"` - // Tag's color - Color string `json:"color"` + TagName string `json:"tagName"` } // NewTagResponse instantiates a new TagResponse object // This constructor will assign default values to properties that have it defined, // and makes sure properties required by API are set, but the set of arguments // will change when the set of required properties is changed -func NewTagResponse(tenantId string, customerId string, tagId float32, name string, color string) *TagResponse { +func NewTagResponse(tagId float32, tagName string) *TagResponse { this := TagResponse{} - this.TenantId = tenantId - this.CustomerId = customerId this.TagId = tagId - this.Name = name - this.Color = color + this.TagName = tagName return &this } @@ -51,54 +42,6 @@ func NewTagResponseWithDefaults() *TagResponse { return &this } -// GetTenantId returns the TenantId field value -func (o *TagResponse) GetTenantId() string { - if o == nil { - var ret string - return ret - } - - return o.TenantId -} - -// GetTenantIdOk returns a tuple with the TenantId field value -// and a boolean to check if the value has been set. -func (o *TagResponse) GetTenantIdOk() (*string, bool) { - if o == nil { - return nil, false - } - return &o.TenantId, true -} - -// SetTenantId sets field value -func (o *TagResponse) SetTenantId(v string) { - o.TenantId = v -} - -// GetCustomerId returns the CustomerId field value -func (o *TagResponse) GetCustomerId() string { - if o == nil { - var ret string - return ret - } - - return o.CustomerId -} - -// GetCustomerIdOk returns a tuple with the CustomerId field value -// and a boolean to check if the value has been set. -func (o *TagResponse) GetCustomerIdOk() (*string, bool) { - if o == nil { - return nil, false - } - return &o.CustomerId, true -} - -// SetCustomerId sets field value -func (o *TagResponse) SetCustomerId(v string) { - o.CustomerId = v -} - // GetTagId returns the TagId field value func (o *TagResponse) GetTagId() float32 { if o == nil { @@ -123,70 +66,37 @@ func (o *TagResponse) SetTagId(v float32) { o.TagId = v } -// GetName returns the Name field value -func (o *TagResponse) GetName() string { +// GetTagName returns the TagName field value +func (o *TagResponse) GetTagName() string { if o == nil { var ret string return ret } - return o.Name + return o.TagName } -// GetNameOk returns a tuple with the Name field value +// GetTagNameOk returns a tuple with the TagName field value // and a boolean to check if the value has been set. -func (o *TagResponse) GetNameOk() (*string, bool) { +func (o *TagResponse) GetTagNameOk() (*string, bool) { if o == nil { return nil, false } - return &o.Name, true + return &o.TagName, true } -// SetName sets field value -func (o *TagResponse) SetName(v string) { - o.Name = v -} - -// GetColor returns the Color field value -func (o *TagResponse) GetColor() string { - if o == nil { - var ret string - return ret - } - - return o.Color -} - -// GetColorOk returns a tuple with the Color field value -// and a boolean to check if the value has been set. -func (o *TagResponse) GetColorOk() (*string, bool) { - if o == nil { - return nil, false - } - return &o.Color, true -} - -// SetColor sets field value -func (o *TagResponse) SetColor(v string) { - o.Color = v +// SetTagName sets field value +func (o *TagResponse) SetTagName(v string) { + o.TagName = v } func (o TagResponse) MarshalJSON() ([]byte, error) { toSerialize := map[string]interface{}{} - if true { - toSerialize["tenantId"] = o.TenantId - } - if true { - toSerialize["customerId"] = o.CustomerId - } if true { toSerialize["tagId"] = o.TagId } if true { - toSerialize["name"] = o.Name - } - if true { - toSerialize["color"] = o.Color + toSerialize["tagName"] = o.TagName } return json.Marshal(toSerialize) } diff --git a/openapi/model_tag_response1.go b/openapi/model_tag_response1.go index b789550..d528cc0 100644 --- a/openapi/model_tag_response1.go +++ b/openapi/model_tag_response1.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com @@ -17,20 +17,29 @@ import ( // TagResponse1 struct for TagResponse1 type TagResponse1 struct { + // Your customer tenant id + TenantId string `json:"tenantId"` + // Your customer number + CustomerId string `json:"customerId"` // Tag's id TagId float32 `json:"tagId"` // Tag's name - TagName string `json:"tagName"` + Name string `json:"name"` + // Tag's color + Color string `json:"color"` } // NewTagResponse1 instantiates a new TagResponse1 object // This constructor will assign default values to properties that have it defined, // and makes sure properties required by API are set, but the set of arguments // will change when the set of required properties is changed -func NewTagResponse1(tagId float32, tagName string) *TagResponse1 { +func NewTagResponse1(tenantId string, customerId string, tagId float32, name string, color string) *TagResponse1 { this := TagResponse1{} + this.TenantId = tenantId + this.CustomerId = customerId this.TagId = tagId - this.TagName = tagName + this.Name = name + this.Color = color return &this } @@ -42,6 +51,54 @@ func NewTagResponse1WithDefaults() *TagResponse1 { return &this } +// GetTenantId returns the TenantId field value +func (o *TagResponse1) GetTenantId() string { + if o == nil { + var ret string + return ret + } + + return o.TenantId +} + +// GetTenantIdOk returns a tuple with the TenantId field value +// and a boolean to check if the value has been set. +func (o *TagResponse1) GetTenantIdOk() (*string, bool) { + if o == nil { + return nil, false + } + return &o.TenantId, true +} + +// SetTenantId sets field value +func (o *TagResponse1) SetTenantId(v string) { + o.TenantId = v +} + +// GetCustomerId returns the CustomerId field value +func (o *TagResponse1) GetCustomerId() string { + if o == nil { + var ret string + return ret + } + + return o.CustomerId +} + +// GetCustomerIdOk returns a tuple with the CustomerId field value +// and a boolean to check if the value has been set. +func (o *TagResponse1) GetCustomerIdOk() (*string, bool) { + if o == nil { + return nil, false + } + return &o.CustomerId, true +} + +// SetCustomerId sets field value +func (o *TagResponse1) SetCustomerId(v string) { + o.CustomerId = v +} + // GetTagId returns the TagId field value func (o *TagResponse1) GetTagId() float32 { if o == nil { @@ -66,37 +123,70 @@ func (o *TagResponse1) SetTagId(v float32) { o.TagId = v } -// GetTagName returns the TagName field value -func (o *TagResponse1) GetTagName() string { +// GetName returns the Name field value +func (o *TagResponse1) GetName() string { if o == nil { var ret string return ret } - return o.TagName + return o.Name } -// GetTagNameOk returns a tuple with the TagName field value +// GetNameOk returns a tuple with the Name field value // and a boolean to check if the value has been set. -func (o *TagResponse1) GetTagNameOk() (*string, bool) { +func (o *TagResponse1) GetNameOk() (*string, bool) { if o == nil { return nil, false } - return &o.TagName, true + return &o.Name, true } -// SetTagName sets field value -func (o *TagResponse1) SetTagName(v string) { - o.TagName = v +// SetName sets field value +func (o *TagResponse1) SetName(v string) { + o.Name = v +} + +// GetColor returns the Color field value +func (o *TagResponse1) GetColor() string { + if o == nil { + var ret string + return ret + } + + return o.Color +} + +// GetColorOk returns a tuple with the Color field value +// and a boolean to check if the value has been set. +func (o *TagResponse1) GetColorOk() (*string, bool) { + if o == nil { + return nil, false + } + return &o.Color, true +} + +// SetColor sets field value +func (o *TagResponse1) SetColor(v string) { + o.Color = v } func (o TagResponse1) MarshalJSON() ([]byte, error) { toSerialize := map[string]interface{}{} + if true { + toSerialize["tenantId"] = o.TenantId + } + if true { + toSerialize["customerId"] = o.CustomerId + } if true { toSerialize["tagId"] = o.TagId } if true { - toSerialize["tagName"] = o.TagName + toSerialize["name"] = o.Name + } + if true { + toSerialize["color"] = o.Color } return json.Marshal(toSerialize) } diff --git a/openapi/model_ticket_create_request.go b/openapi/model_ticket_create_request.go index 762d08b..edae20d 100644 --- a/openapi/model_ticket_create_request.go +++ b/openapi/model_ticket_create_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_ticket_create_response.go b/openapi/model_ticket_create_response.go index 0fc89c3..67dee70 100644 --- a/openapi/model_ticket_create_response.go +++ b/openapi/model_ticket_create_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_ticket_response.go b/openapi/model_ticket_response.go index adfaa4e..fe3263f 100644 --- a/openapi/model_ticket_response.go +++ b/openapi/model_ticket_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_unassign_instance_private_network_response.go b/openapi/model_unassign_instance_private_network_response.go index 4cecb58..094032d 100644 --- a/openapi/model_unassign_instance_private_network_response.go +++ b/openapi/model_unassign_instance_private_network_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_custom_image_request.go b/openapi/model_update_custom_image_request.go index ba89134..01f30b0 100644 --- a/openapi/model_update_custom_image_request.go +++ b/openapi/model_update_custom_image_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_custom_image_response.go b/openapi/model_update_custom_image_response.go index 247b38a..5303e24 100644 --- a/openapi/model_update_custom_image_response.go +++ b/openapi/model_update_custom_image_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_custom_image_response_data.go b/openapi/model_update_custom_image_response_data.go index a853735..905b994 100644 --- a/openapi/model_update_custom_image_response_data.go +++ b/openapi/model_update_custom_image_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_role_request.go b/openapi/model_update_role_request.go index cea5e8f..db619cb 100644 --- a/openapi/model_update_role_request.go +++ b/openapi/model_update_role_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_role_response.go b/openapi/model_update_role_response.go index b45aaf6..2428ee9 100644 --- a/openapi/model_update_role_response.go +++ b/openapi/model_update_role_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_secret_request.go b/openapi/model_update_secret_request.go index 0d49472..777cc9a 100644 --- a/openapi/model_update_secret_request.go +++ b/openapi/model_update_secret_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_secret_response.go b/openapi/model_update_secret_response.go index 0980b35..ae4dae1 100644 --- a/openapi/model_update_secret_response.go +++ b/openapi/model_update_secret_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_snapshot_request.go b/openapi/model_update_snapshot_request.go index e4e8d49..b8a4260 100644 --- a/openapi/model_update_snapshot_request.go +++ b/openapi/model_update_snapshot_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_snapshot_response.go b/openapi/model_update_snapshot_response.go index 0624195..9c4c074 100644 --- a/openapi/model_update_snapshot_response.go +++ b/openapi/model_update_snapshot_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_tag_request.go b/openapi/model_update_tag_request.go index a593a63..365f50f 100644 --- a/openapi/model_update_tag_request.go +++ b/openapi/model_update_tag_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_tag_response.go b/openapi/model_update_tag_response.go index 8e242a4..712ebf1 100644 --- a/openapi/model_update_tag_response.go +++ b/openapi/model_update_tag_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_user_request.go b/openapi/model_update_user_request.go index 5512175..506746c 100644 --- a/openapi/model_update_user_request.go +++ b/openapi/model_update_user_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_update_user_response.go b/openapi/model_update_user_response.go index 889ed4c..f723ba2 100644 --- a/openapi/model_update_user_response.go +++ b/openapi/model_update_user_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_upgrade_auto_scaling_type.go b/openapi/model_upgrade_auto_scaling_type.go index 9d4272b..87d03ce 100644 --- a/openapi/model_upgrade_auto_scaling_type.go +++ b/openapi/model_upgrade_auto_scaling_type.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_upgrade_instance_request.go b/openapi/model_upgrade_instance_request.go index cd326e3..0d1f475 100644 --- a/openapi/model_upgrade_instance_request.go +++ b/openapi/model_upgrade_instance_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_upgrade_object_storage_request.go b/openapi/model_upgrade_object_storage_request.go index 70705e3..689774c 100644 --- a/openapi/model_upgrade_object_storage_request.go +++ b/openapi/model_upgrade_object_storage_request.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_upgrade_object_storage_response.go b/openapi/model_upgrade_object_storage_response.go index 2f0d2ad..9ae6284 100644 --- a/openapi/model_upgrade_object_storage_response.go +++ b/openapi/model_upgrade_object_storage_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_upgrade_object_storage_response_data.go b/openapi/model_upgrade_object_storage_response_data.go index 4b9495e..14de8c7 100644 --- a/openapi/model_upgrade_object_storage_response_data.go +++ b/openapi/model_upgrade_object_storage_response_data.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_user_audit_response.go b/openapi/model_user_audit_response.go index 91f8357..37abb14 100644 --- a/openapi/model_user_audit_response.go +++ b/openapi/model_user_audit_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_user_is_password_set_response.go b/openapi/model_user_is_password_set_response.go index 8645e3a..6daace1 100644 --- a/openapi/model_user_is_password_set_response.go +++ b/openapi/model_user_is_password_set_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_user_response.go b/openapi/model_user_response.go index fab5cb2..31b70ca 100644 --- a/openapi/model_user_response.go +++ b/openapi/model_user_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/model_vnc_response.go b/openapi/model_vnc_response.go index 09b7145..561f8bf 100644 --- a/openapi/model_vnc_response.go +++ b/openapi/model_vnc_response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/response.go b/openapi/response.go index 521399d..563a401 100644 --- a/openapi/response.go +++ b/openapi/response.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com diff --git a/openapi/utils.go b/openapi/utils.go index d2f1c0d..bd67c1c 100644 --- a/openapi/utils.go +++ b/openapi/utils.go @@ -1,7 +1,7 @@ /* Contabo API -# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). +# Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. [CLI Download and Installation instructions.](https://github.com/contabo/cntb) ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the [Contabo Product Documentation](https://docs.contabo.com/). ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the [Customer Control Panel](https://my.contabo.com/api/details): 1. ClientId 2. ClientSecret 3. API User (your email address to login to the [Customer Control Panel](https://my.contabo.com/api/details)) 4. API Password (this is a new password which you'll set or change in the [Customer Control Panel](https://my.contabo.com/api/details)) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. ```sh CLIENT_ID= CLIENT_SECRET= API_USER= API_PASSWORD='' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq ``` #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. ```powershell $client_id='' $client_secret='' $api_user='' $api_password='' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ``` ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) [here](https://github.com/contabo/cntb) 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials ```sh cntb config set-credentials --oauth2-clientid= --oauth2-client-secret= --oauth2-user= --oauth2-password='' ``` 5. Use the CLI ```sh # get list of your instances cntb get instances # help cntb help ``` ## API Overview ### [Compute Management](#tag/Instances) The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of [cloud-init](https://cloud-init.io/) at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### [Object Storage](#tag/Object-Storages) The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for [S3](https://en.wikipedia.org/wiki/Amazon_S3) compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like [`aws`](https://aws.amazon.com/cli/) cli or similar. ### [Private Networking](#tag/Private-Networks) The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### [Secrets Management](#tag/Secrets) You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### [User Management](#tag/Users) If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of [tags](#tag-management). These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### [Tag Management](#tag/Tags) The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the [User Management API](#user-management). For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources. POST | Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON. PATCH | Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation. PUT | Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values. DELETE | Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message. ## Responses Usually the Contabo API should respond to your requests. The data returned is in [JSON](https://www.json.org/) format allowing easy processing in any programming language or tools. As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes. Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed. Response Code | Description --- | --- 200 | The response contains your requested information. 201 | Your request was accepted. The resource was created. 204 | Your request succeeded, there is no additional information returned. 400 | Your request was malformed. 401 | You did not supply valid authentication credentials. 402 | Request refused as it requires additional payed service. 403 | You are not allowed to perform the request. 404 | No results were found for your request or resource does not exist. 409 | Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources. 429 | Rate-limit reached. Please wait for some time before doing more requests. 500 | We were unable to perform the request due to server-side problems. In such cases please retry or contact the support. Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore (\"_\") like `_links` or `_pagination`. The actual data is returned in a field called `data`. For convenience reasons this `data` field is always returned as an array even if it consists of only one single element. Some general details about Contabo API from [Contabo](https://contabo.com). API version: 1.0.0 Contact: support@contabo.com