diff --git a/README.md b/README.md index f6b66d5..f8e5466 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ -# Getting support +# ⚠️ Deprecation Notice + +> [!WARNING] +> This API has not been updated since 2021 is scheduled for deprecation. Please use our new GraphQL API at https://developers.zenhub.com -If you have any questions or feedback, **contact [support](mailto:support@zenhub.com) for support**. The ZenHub Board for this repo has been sunset - all support inquiries should be submitted directly through the email above. +# Getting support -You can also submit a feature request [here](https://portal.productboard.com/zenhub). +If you have any questions or feedback, **contact [support](mailto:support@zenhub.com)**. You can submit feature requests [here](https://portal.productboard.com/zenhub). # Overview @@ -28,7 +31,7 @@ You can also submit a feature request [here](https://portal.productboard.com/zen - [Convert an Epic to an Issue](#convert-an-epic-to-an-issue) - [Convert an Issue to Epic](#convert-issue-to-epic) - [Add or Remove Issues from an Epic](#add-or-remove-issues-to-epic) -- [Workspaces](#workspaces) +- [Workspaces](#workspace) - [Get ZenHub Workspaces for a repository](#get-zenhub-workspaces-for-a-repository) - [Get a ZenHub Board for a repository](#get-a-zenhub-board-for-a-repository) - [Get the oldest ZenHub Board for a repository](#get-the-oldest-zenhub-board-for-a-repository) @@ -53,17 +56,30 @@ You can also submit a feature request [here](https://portal.productboard.com/zen [Webhooks](#webhooks) - [Custom Webhooks](#custom-webhooks) + - [Content Type: urlencoded](#content-type-urlencoded) [Contact Us](#contact-us) ## Root Endpoint -On Cloud, the root endpoint for the public API is `https://api.zenhub.io/`. -For ZenHub Enterprise, the root endpoint is `https:///`. +The ZenHub API root endpoint for Cloud is different than that of ZenHub On-Premise Enterprise instances and has also changed across Enterprise versions. Please refer to the table below for the appropriate endpoint. + +ZenHub Version | API Root Endpoint +--- | --- +Cloud | `https://api.zenhub.com/` +Enterprise 2 | `https:///` +Enterprise 3 | `https:///api/` ## Authentication -All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/dashboard/tokens) (or `https:///app/dashboard/tokens` for ZenHub Enterprise). The token is sent in the `X-Authentication-Token` header. For example, using `curl` it’d be: +All requests to the API need an API token. Generate a token in the **API Tokens** section of your ZenHub [Dashboard](https://app.zenhub.com/dashboard/tokens) (for ZenHub Enterprise, refer to the table below for the proper link). + +ZenHub Enterprise Version | Auth Token Generation Page +--- | --- +Enterprise 2 | `https:///app/dashboard/tokens` +Enterprise 3 | `https:///dashboard/tokens` + +The token is sent in the `X-Authentication-Token` header. For example, using `curl` it would be: ```sh curl -H 'X-Authentication-Token: TOKEN' URL @@ -74,7 +90,6 @@ Alternatively, you can choose to send the token in the URL using the `access_tok #### Notes - Each user may only have one token, so generating a new token will invalidate previously created tokens. -- For ZenHub Enterprise users, please follow the instructions in `https:///setup/howto/api` ## Content-Type: JSON @@ -112,6 +127,7 @@ The ZenHub API can return the following errors: #### Notes - `repo_id` is the ID of the repository, not its full name. For example, the ID of the `ZenHubIO/API` repository is `47655910`. To find out the ID of your repository, use [GitHub’s API](https://developer.github.com/v3/repos/#get), or copy it from the URL of the Board (for this repo, the Board URL is https://github.com/ZenHubIO/API#boards?repos=47655910). +- `workspace_id` is the ID of the ZenHub Workspace. This is found in the URL for the Workspace after the name of the workspace. For example, the `workspace_id` for `https://app.zenhub.com/workspaces/workflows---product--design-workspace-5f6b5c9ab4fd7d76a3e5b7d8/board?` is `5f6b5c9ab4fd7d76a3e5b7d8`. ## Issues @@ -143,11 +159,6 @@ Get the data for a specific issue. "estimate": { "value": 8 }, - "plus_ones": [ - { - "created_at": "2015-12-11T18:43:22.296Z" - } - ], "pipeline": { "name": "QA", "pipeline_id": "5d0a7a9741fd098f6b7f58a7", @@ -171,10 +182,10 @@ Get the data for a specific issue. #### Notes -- `plus_ones[].user_id` was removed from the response. - `pipeline` object references the oldest Workspace pipeline this issue is in. + - **NOTE:** If an issue's status is closed, the `pipeline` value will describe the Pipeline that the issue was in prior to the issue being closed. The ZenHub API does not consider the "Closed" Pipeline to be a distinct Pipeline at this time and you should **not** use the Pipeline value to determine whether or not an issue is closed or open (use `status` instead). + - **NOTE:** Reopened issues might take up to one minute to show up in the correct Pipeline. - `pipelines` contains all pipelines in all Workspaces this issue is in. -- Closed issues might take up to one minute to show up in the Closed Pipeline. Similarly, reopened issues might take up to one minute to show in the correct Pipeline. ### Get Issue Events @@ -640,7 +651,7 @@ Bulk add or remove issues to an Epic. The result returns which issue was added o - `add_issues` shows which issues were added in this operation. - Returns a `404` if the Epic doesn’t exist -## Workspaces +## Workspace - [Get ZenHub Workspaces for a repository](#get-zenhub-workspaces-for-a-repository) - [Get a ZenHub Board for a repository](#get-a-zenhub-board-for-a-repository) @@ -1335,7 +1346,14 @@ For instructions, you'll notice the `How to create a webhook` link changes dynam ### Custom webhooks -Our custom webhook sends a POST request to your webhook for multiple events that occur on your ZenHub board: +Our custom webhook sends a POST request to your webhook for multiple events that occur on your ZenHub board. See below for examples of the events and data that they will contain. Please note that the content type in the examples has been written in JSON, however the actual data is sent in **x-www-form-urlencoded** format. + +#### Content Type: urlencoded + +The POST request is sent in the **x-www-form-urlencoded** format. + +Example: +```field1=value1&field2=value2``` #### Issue transfer @@ -1349,6 +1367,8 @@ Our custom webhook sends a POST request to your webhook for multiple events that "issue_number": "618", "issue_title": "ZenHub Change Log", "to_pipeline_name": "New Issues", + "workspace_id": "603fc3e575de63001cc163f9", + "workspace_name": "My Workspace", "from_pipeline_name": "Discussion" } ``` @@ -1395,7 +1415,9 @@ Our custom webhook sends a POST request to your webhook for multiple events that "issue_title": "ZenHub Change Log", "to_pipeline_name": "Backlog", "from_position": "4", - "to_position": "0" + "to_position": "0", + "workspace_id": "603fc3e575de63001cc163f9", + "workspace_name" "My Workspace" } ``` @@ -1420,4 +1442,4 @@ app.post('*', function(req, res) { # Contact us -We’d love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, open an issue in our [Support repo](https://github.com/ZenHubIO/support/issues#boards) or find us on [Twitter](http://www.twitter.com/ZenHubHQ). +We’d love to hear from you. If you have any questions, concerns, or ideas related to the ZenHub API, please reach us at [support@zenhub.com](mailto:support@zenhub.com) or find us on [Twitter](https://twitter.com/zenhubstatus).