pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-07-16 19:09:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: explain resource identifiers

Browse Source
This commit is contained in:
Laurence
2026-05-26 16:32:21 +01:00
parent bd5090b4bc
commit d56f598d5c
2 changed files with 16 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
manage/blueprints.mdx
View File

@@ -43,6 +43,8 @@ sites:
Think of the resource key as your stable ID inside the blueprint. The fields under that key describe what Pangolin should create or maintain.
These keys are the same idea as the **Identifier** shown in the Pangolin app, called `niceId` in the API. Choose readable, stable keys such as `warehouse-west` or `web-app`; blueprints use them to match and update the same sites and resources on later applies. For more detail, see [What is an identifier?](/manage/common-api-routes#what-is-an-identifier).
## Choose A Format
Pangolin supports two blueprint formats:

15
manage/common-api-routes.mdx
View File

@@ -9,6 +9,19 @@ All routes in this guide require an API key. See [Integration API](/manage/integ
This guide is a **minimal** walkthrough for creating core Pangolin components (sites, resources, targets) via the API. It is not exhaustive — some elements are omitted for simplicity — but everything shown here works and illustrates patterns used elsewhere in the API. For full coverage of endpoints (get, update, delete, list, etc.), use the [Swagger docs](https://api.pangolin.net/v1/docs).
</Note>
## What is an identifier?
In the Pangolin app, sites, public resources, private resources, and clients have an **Identifier**. In the API, this value is called `niceId`.
The identifier is a human-readable, organization-unique value you can use when you want something more stable and memorable than a numeric ID. For example, a site might have a numeric `siteId` like `8723` and a `niceId` like `warehouse-west`.
Identifiers are especially useful for automation:
- In [Blueprints](/manage/blueprints), resource and site keys act as stable identifiers. A target can reference a site by its identifier, such as `site: warehouse-west`.
- In the API, responses include both the numeric ID and `niceId` when the object supports identifiers. Some routes can also look up objects by `niceId`, such as `GET /org/{orgId}/site/{niceId}` for sites.
Use the numeric ID when an endpoint asks for `siteId`, `resourceId`, or `siteResourceId`. Use `niceId` when an endpoint or blueprint field asks for an identifier.
## Create site
This section assumes you're creating a **Newt** site. For all Site endpoints, see [Site API (Swagger)](https://api.pangolin.net/v1/docs/#/Site).
@@ -373,4 +386,4 @@ Both return `{ "data": {}, "success": true, "error": false, "message": "...", "s
**POST** `/site-resource/{siteResourceId}/users/add` — **Path:** `siteResourceId` (number). **Body:** `{ "userId": string }`.
Same response shape as above. Role must belong to the same org as the site resource. For more endpoints (list/remove), see [Resource API](https://api.pangolin.net/v1/docs/#/Resource).
Same response shape as above. Role must belong to the same org as the site resource. For more endpoints (list/remove), see [Resource API](https://api.pangolin.net/v1/docs/#/Resource).