You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: jekyll/_cci2/api-developers-guide.md
+30-5Lines changed: 30 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -90,21 +90,46 @@ v1) return EDN if no accept header is specified.
90
90
## Getting started with the API
91
91
{: #getting-started-with-the-api }
92
92
93
-
The CircleCI API shares similarities with previous API versions in that it identifies your projects using repository name. For instance, if you want to pull information from CircleCI about the GitHub repository "https://github.com/CircleCI-Public/circleci-cli" you can refer to that in the CircleCI API as `gh/CircleCI-Public/circleci-cli`, which is a _triplet_ of the project type (VCS provider), the name of your engineering organization (or your VCS username), and the name of the repository.
93
+
### GitHub and Bitbucket projects
94
+
{: #github-and-bitbucket-projects }
94
95
95
-
For the project type you can use `github` or `bitbucket` as well as the shorter forms `gh` or `bb`. For any other VCS type you can use `circleci`. The `organization` is your username or organization name in your version control system.
96
+
The CircleCI API shares similarities with previous API versions in that it identifies your projects using repository name. For instance, if you want to pull information from CircleCI about the GitHub repository "https://github.com/CircleCI-Public/circleci-cli" you can refer to that in the CircleCI API as `gh/CircleCI-Public/circleci-cli`, which is a _triplet_ of the VCS type (VCS provider), the name of your engineering organization (or your VCS username), and the name of the repository.
97
+
98
+
For the VCS type you can use `github` or `bitbucket` as well as the shorter forms `gh` or `bb`. The `organization` is your username or organization name in your version control system.
96
99
97
100
With this API, CircleCI introduces a string representation of the triplet called the `project_slug`, which takes the following form:
98
101
99
102
```
100
-
{project_type}/{org_name}/{repo_name}
103
+
{vcs_type}/{org_name}/{repo_name}
101
104
```
102
105
103
106
The `project_slug` is included in the payload when pulling information about a project, and when looking up a pipeline or workflow by ID. The `project_slug` can then be used to get information about the project.
It is possible in the future the shape of a `project_slug` may change, but in all cases it would be usable as a human-readable identifier for a given project.
110
+
For GitHub and Bitbucket projects, `project_slug` is currently usable as a human-readable identifier for a given project. For [GitLab projects](#gitlab-saas-support-projects), the slug format has been changed.
111
+
112
+
### GitLab SaaS Support projects
113
+
{: #gitlab-saas-support-projects }
114
+
115
+
For GitLab Saas Support, organization as well as project names do not serve as identifiers, and are not part of project slugs. GitLab projects currently use a new slug format:
116
+
117
+
`circleci/:slug-remainder`
118
+
119
+
The project slug forGitLab projects can be found by navigating to your projectin the CircleCI web app and taking the "triplet" string from the browser address bar.
120
+
121
+
122
+
123
+
In API requests, the project slug must be passed as a whole. For example:
GitLab project slugs must be treated as opaque strings. The slug should not be parsed to retrieve the project or organization IDs. To retrieve project and organization IDs or names, use the entire slug to fetch [project details](#get-project-details) or organization details. The IDs and names are included in the payload.
108
133
109
134
## Rate limits
110
135
{: #rate-limits }
@@ -297,7 +322,7 @@ Whenever you see curly brackets `{}`, this represents a variable that you must m
297
322
298
323
To return project details, perform the following steps:
299
324
300
-
1. For this GET API call, under the `parameters` key, define the `project_slug` (`\<project_type\>/\<org_name\>/\<repo_name\>`) parameter you want returned in the JSON payload in your `curl` request as follows:
325
+
1. For this GET API call, under the `parameters` key, define the `project_slug` (`\<vcs_type\>/\<org_name\>/\<repo_name\>`) parameter you want returned in the JSON payload in your `curl` request as follows:
301
326
302
327
```shell
303
328
curl -X GET https://circleci.com/api/v2/project/{project_slug} \
Copy file name to clipboardExpand all lines: jekyll/_cci2/api-intro.md
+11-13Lines changed: 11 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -37,13 +37,20 @@ Currently, [Personal API tokens]({{site.baseurl}}/managing-api-tokens/#creating-
37
37
## Getting started with the API v2
38
38
{: #getting-started-with-the-api-v2 }
39
39
40
-
The CircleCI API v2 is backwards-compatible with previous API versions in the way it identifies your projects using repository name. For instance, if you want to pull information from CircleCI about the GitHub repository https://github.com/CircleCI-Public/circleci-cli you can refer to that in the CircleCI API as `gh/CircleCI-Public/circleci-cli`, which is a "triplet" of the project type, the name of your "organization", and the name of the repository. For the project type you can use `github` or `bitbucket` as well as the shorter forms `gh` or `bb`, which are now supported in API v2. The `organization` is your username or organization name in your version control system.
40
+
**GitLab SaaS Support users:** Note that the definition of **project slug** provided in this section, as well as its usage throughout this document applies to GitHub and Bitbucket projects only. GitLab projects currently use a new slug format:
41
+
<br>
42
+
`circleci/:slug-remainder`
43
+
<br>
44
+
The project slug for GitLab projects can be found by navigating to your project in the CircleCI web app and taking the string from the browser address bar. The slug must be treated as an opaque string and passed in its entirety in API requests. Read the [API Developer's Guide]({{site.baseurl}}/api-developers-guide) for more details.
45
+
{: class="alert alert-info"}
46
+
47
+
The CircleCI API v2 is backwards-compatible with previous API versions in the way it identifies your projects using repository name. For instance, if you want to pull information from CircleCI about the GitHub repository https://github.com/CircleCI-Public/circleci-cli you can refer to that in the CircleCI API as `gh/CircleCI-Public/circleci-cli`, which is a "triplet" of the VCS type, the name of your "organization", and the name of the repository. For the VCS type you can use `github` or `bitbucket` as well as the shorter forms `gh` or `bb`, which are now supported in API v2. The `organization` is your username or organization name in your version control system.
41
48
42
49
With API v2, CircleCI is introducing a string representation of the triplet called the `project_slug`, which takes the following form:
43
50
44
-
`<project_type>/<org_name>/<repo_name>`
51
+
`<vcs_type>/<org_name>/<repo_name>`
45
52
46
-
The `project_slug` is included in the payload when pulling information about a project as well as when looking up a pipeline or workflow by ID. The `project_slug` can then be used to get information about the project. It is possible in the future the shape of a `project_slug` may change, but in all cases it would be usable as a human-readable identifier for a given project.
53
+
The `project_slug` is included in the payload when pulling information about a project as well as when looking up a pipeline or workflow by ID. The `project_slug` can then be used to get information about the project. It is possible in the future the shape of a `project_slug` may change, but for GitHub and Bitbucket projects it is currently usable as a human-readable identifier for a given project.
47
54
48
55
## Authentication
49
56
{: #authentication }
@@ -97,7 +104,7 @@ Endpoint | Description
97
104
### Deprecated endpoints
98
105
{: #deprecated-endpoints }
99
106
100
-
For this updated API v2 release, several endpoints have been deprecated, which are listed in the table below.
107
+
With API v2, several endpoints from v1 have been deprecated, which are listed in the table below.
API v2 is not supported for installations of CircleCI server 2.x. API v2 is supported for self-hosted installations of CircleCI server 3.x.
112
119
113
-
## Data insights
114
-
{: #data-insights }
115
-
116
-
The CircleCI API v2 enables you to call a specific set of endpoints to retrieve detailed [insights]({{site.baseurl}}/insights) and data about your jobs and workflows. This information can help you better understand how your jobs and workflows are performing while also providing you with data points that you can use to optimize your workflows and builds. Some examples of insights endpoints include:
- Review the [API Developer's Guide]({{site.baseurl}}/api-developers-guide) for a detailed walkthrough on authenticating as well as example API requests.
0 commit comments