-
Notifications
You must be signed in to change notification settings - Fork 92
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2229 from OctopusDeploy/tk/rest-api-overview-page
Octopus REST API updates
- Loading branch information
Showing
3 changed files
with
164 additions
and
132 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,148 @@ | ||
| --- | ||
| layout: src/layouts/Default.astro | ||
| pubDate: 2024-04-10 | ||
| modDate: 2024-04-10 | ||
| title: Getting started with the Octopus REST API | ||
| navTitle: Getting started with the Octopus REST API | ||
| description: Getting started with the Octopus REST API | ||
| navOrder: 10 | ||
| --- | ||
|
|
||
| ## API clients | ||
|
|
||
| Octopus provides API clients for popular programming languages and runtime environments. You can access the source code for these clients on GitHub: | ||
|
|
||
| - [Go API Client for Octopus Deploy](https://github.com/OctopusDeploy/go-octopusdeploy) | ||
| - [Java API Client for Octopus Deploy](https://github.com/OctopusDeployLabs/java-octopus-deploy) | ||
| - [.NET C# API Client for Octopus Deploy](https://github.com/OctopusDeploy/OctopusClients) | ||
| - [TypeScript API Client for Octopus Deploy](https://github.com/OctopusDeploy/api-client.ts) | ||
|
|
||
| Code snippets using these clients for operations in the Octopus REST API are available in our [API examples](/docs/octopus-rest-api/examples) documentation. | ||
|
|
||
| ## REST API authentication \{#authentication} | ||
|
|
||
| The Octopus Deploy API is available at: | ||
|
|
||
| ``` | ||
| https://<your-octopus-url>/api | ||
| ``` | ||
|
|
||
| Replace `<your-octopus-url>` with the URL that you host your Octopus instance on. | ||
|
|
||
| The API supports 2 methods of authentication. | ||
|
|
||
| ### Creating an API Key | ||
|
|
||
| You can get your API key from your profile page on the Octopus Web Portal. | ||
|
|
||
| After you have a key, you can provide it to the API in the following ways: | ||
|
|
||
| 1. Through the `X-Octopus-ApiKey` HTTP header with all requests. This is the preferred approach. | ||
| 1. As an `apikey` query string parameter with all requests. You should only be used for simple requests. | ||
|
|
||
| :::div{.hint} | ||
| Learn more about [how to create an API key](/docs/octopus-rest-api/how-to-create-an-api-key). | ||
| ::: | ||
|
|
||
| ### OpenID Connect | ||
|
|
||
| OpenID Connect is a set of identity specifications that build on OAuth 2.0 to let software systems connect in a way that promotes security best practices. | ||
|
|
||
| When using OIDC, Octopus validates an identity token from a trusted external system using [public key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). Octopus then issues a short-lived access token that you can use to interact with the Octopus API. | ||
|
|
||
| Some of the benefits of using OIDC in Octopus include: | ||
|
|
||
| - You don't need to provision API keys and store them in external systems. This reduces the risk of unauthorized access to the Octopus API from exposed keys. | ||
| - Administrators don't need to rotate API keys manually. This reduces the risk of disruption when updating to newer keys in external systems. | ||
| - Access tokens issued by Octopus are short-lived. This reduces the risk of unauthorized access to the Octopus API. | ||
| - Access tokens are only issued for requests from trusted external systems. This allows for controlled access to service accounts and promotes the principle of least access. | ||
|
|
||
| We support any issuer that can generate signed OIDC tokens that can be validated anonymously. However, we provide built-in support for GitHub Actions with the [OctopusDeploy/login](https://github.com/OctopusDeploy/login) action. | ||
|
|
||
| For more information see [Using OpenId Connect with the Octopus API](https://octopus.com/docs/octopus-rest-api/openid-connect). | ||
|
|
||
| ## REST API Swagger documentation \{#api-swagger-docs} | ||
|
|
||
| Octopus includes the default Swagger UI for displaying the API documentation in a nice, human, readable way. To browse that UI just open your browser and go to `https://<your-octopus-url>/swaggerui/`. The original Non-Swagger API page is still available and you can access it via `https://<your-octopus-url>/api/`. | ||
|
|
||
| :::figure | ||
|  | ||
| ::: | ||
|
|
||
| You can view the API through the Octopus Demo server at [demo.octopus.app/swaggerui/index.html](https://demo.octopus.app/swaggerui/index.html). | ||
|
|
||
| ## REST API links \{#api-links} | ||
|
|
||
| All resources returned by the REST API contain links to other resources. The idea is that instead of memorizing or hard-coding URLs when using the API, you should start with the root API resource and use links to navigate. | ||
|
|
||
| For example, a `GET` request to `/api` returns a resource that looks like: | ||
|
|
||
| ```json | ||
| { | ||
| "Application": "Octopus Deploy", | ||
| "Version": "2022.1.2386", | ||
| "ApiVersion": "3.0.0", | ||
| "InstallationId": "9f155416-5d9e-4e19-ba58-b710d4edf336", | ||
| "Links": { | ||
| "Self": "/api", | ||
| "Accounts": "/api/Spaces-1/accounts{/id}{?skip,take,ids,partialName,accountType}", | ||
| "Environments": "/api/Spaces-1/environments{/id}{?name,skip,ids,take,partialName}", | ||
| "Machines": "/api/Spaces-1/machines{/id}{?skip,take,name,ids,partialName,roles,isDisabled,healthStatuses,commStyles,tenantIds,tenantTags,environmentIds,thumbprint,deploymentId,shellNames,deploymentTargetTypes}", | ||
| "Projects": "/api/Spaces-1/projects{/id}{?name,skip,ids,clone,take,partialName,clonedFromProjectId}", | ||
| "RunbookProcesses": "/api/Spaces-1/runbookProcesses{/id}{?skip,take,ids}", | ||
| "RunbookRuns": "/api/Spaces-1/runbookRuns{/id}{?skip,take,ids,projects,environments,tenants,runbooks,taskState,partialName}", | ||
| "Runbooks": "/api/Spaces-1/runbooks{/id}{?skip,take,ids,partialName,clone,projectIds}", | ||
| "RunbookSnapshots": "/api/Spaces-1/runbookSnapshots{/id}{?skip,take,ids,publish}", | ||
| "Feeds": "/api/feeds{/id}{?skip,take,ids,partialName,feedType,name}", | ||
| "Tasks": "/api/tasks{/id}{?skip,active,environment,tenant,runbook,project,name,node,running,states,hasPendingInterruptions,hasWarningsOrErrors,take,ids,partialName,spaces,includeSystem,description,fromCompletedDate,toCompletedDate,fromQueueDate,toQueueDate,fromStartDate,toStartDate}", | ||
| "Variables": "/api/Spaces-1/variables{/id}{?ids}", | ||
| "Web": "/app" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| :::div{.hint} | ||
| Note: the `Links` collection example above has been significantly reduced in size for demonstration purposes. | ||
| ::: | ||
|
|
||
| You can follow the links in the result to navigate around the API. For example, by following the `Projects` link, you'll find a list of the projects on your Octopus server. | ||
|
|
||
| Since the format and structure of links may change, it's essential that clients avoid hardcoding URL's to resources, and instead rely on starting at `/api` and navigating from there. | ||
|
|
||
| ### URI templates | ||
|
|
||
| Some links (mainly to collections) use URI templates as defined in [RFC 6570](http://tools.ietf.org/html/rfc6570). If in doubt, a client should assume that any link is a URI template. | ||
|
|
||
| ### Collections | ||
|
|
||
| Collections of resources also include links. For example, following the `Environments` link above will give you a list of environments. | ||
|
|
||
| ```json | ||
| { | ||
| "ItemType": "Environment", | ||
| "TotalResults": 20, | ||
| "ItemsPerPage": 10, | ||
| "NumberOfPages": 2, | ||
| "LastPageNumber": 1, | ||
| "Items": [ | ||
| // ... a list of environments ... | ||
| ], | ||
| "Links": { | ||
| "Self": "/api/Spaces-1/environments?skip=0&take=10", | ||
| "Template": "/api/Spaces-1/environments{?skip,ids,take,partialName}", | ||
| "Page.All": "/api/Spaces-1/environments?skip=0&take=2147483647", | ||
| "Page.Next": "/api/Spaces-1/environments?skip=10&take=10", | ||
| "Page.Current": "/api/Spaces-1/environments?skip=0&take=10" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The links at the bottom of the resource allow you to traverse the pages of results. Again, instead of hard-coding query string parameters, you can look for a `Page.Next` link and follow that instead. | ||
|
|
||
| ## REST API and Spaces \{#api-and-spaces} | ||
|
|
||
| If you are using spaces, you need to include the `SpaceID` in your API calls. If you do not include the `SpaceID`, your API calls will automatically use the default space. | ||
|
|
||
| ## REST API code samples \{#api-samples} | ||
|
|
||
| Code snippet samples for various operations in the Octopus REST API are available both in our [API examples](/docs/octopus-rest-api/examples) and on the [OctopusDeploy-API GitHub repository](https://github.com/OctopusDeploy/OctopusDeploy-Api) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| Octopus Deploy is built **API-first**. This means that Octopus is built in layers; all data and operations are available over its REST API. The Octopus Web Portal is built on top of this API so all of the data and operations you can see and perform in the Octopus Web Portal can be performed over the REST API. | ||
| We built Octopus Deploy API-first. This means that Octopus is built in layers. All data and operations are available over its REST API. We built the Octopus Web Portal on top of this API, so all the data and operations you can see and perform in the Octopus Web Portal, you can perform over the REST API. | ||
|
|
||
| Octopus integrates with build servers, scripts, external applications, and anything else with its REST API. | ||
| Octopus connects to build servers, scripts, external applications, and anything else with its REST API. |