Skip to content

Commit b8de56d

Browse files
committed
Add API docs for owners template resource
1 parent bb9d25c commit b8de56d

File tree

3 files changed

+70
-0
lines changed

3 files changed

+70
-0
lines changed

docs/TOC.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@
125125
#### [Catalog](api/catalog-resource.md)
126126
#### [Package content](api/package-base-address-resource.md)
127127
#### [Package details URL](api/package-details-template-resource.md)
128+
#### [Owner URL](api/package-owner-template-resource.md)
128129
#### [Package metadata](api/registration-base-url-resource.md)
129130
#### [Push and delete](api/package-publish-resource.md)
130131
#### [Push symbol packages](api/symbol-package-publish-resource.md)

docs/api/overview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ Resource name | Required
6060
[Catalog](catalog-resource.md) | no | Full record of all package events.
6161
[PackageBaseAddress](package-base-address-resource.md) | yes | Get package content (.nupkg).
6262
[PackageDetailsUriTemplate](package-details-template-resource.md) | no | Construct a URL to access a package details web page.
63+
[OwnerDetailsUriTemplate](owner-details-template-resource.md) | no | Construct a URL to access an owner web page.
6364
[PackagePublish](package-publish-resource.md) | yes | Push and delete (or unlist) packages.
6465
[RegistrationsBaseUrl](registration-base-url-resource.md) | yes | Get package metadata.
6566
[ReportAbuseUriTemplate](report-abuse-resource.md) | no | Construct a URL to access a report abuse web page.
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Owner URL Template, NuGet API
3+
description: The Owner URL template allows clients to display in their UI a web link
4+
author: martinrrm
5+
ms.author: mruizmares
6+
ms.date: 4/15/2024
7+
ms.topic: reference
8+
ms.reviewer:
9+
---
10+
11+
# Owner URL template
12+
13+
It is possible for a client to build a URL that can be used by the user to see owner's page in their web
14+
browser. This is useful when a package source wants to show additional information about an owner that may not fit
15+
within the scope of what the NuGet client application shows.
16+
17+
The resource used for building this URL is the `OwnerDetailsUriTemplate` resource found in the
18+
[service index](service-index.md).
19+
20+
## Versioning
21+
22+
The following `@type` values are used:
23+
24+
@type value | Notes
25+
------------------------------- | -----
26+
OwnerDetailsUriTemplate/6.11.0 | The initial release
27+
28+
## URL template
29+
30+
The URL for the following API is the value of the `@id` property associated with one of the aforementioned
31+
resource `@type` values.
32+
33+
## HTTP methods
34+
35+
Although the client is not intended to make requests to the owner URL on behalf of the user, the web page
36+
should support the `GET` method to allow a clicked URL to be easily opened in a web browser.
37+
38+
## Construct the URL
39+
40+
Given a known owner ID, the client implementation can construct a URL used to access a web interface. The
41+
client implementation should display this constructed URL (or clickable link) to the user allowing them to open a web
42+
browser to the URL and to learn more about the owner. The contents of the owner page is determined by the
43+
server implementation.
44+
45+
The URL must be an absolute URL and the scheme (protocol) must be HTTPS.
46+
47+
The value of the `@id` in the service index is a URL string containing any of the following placeholder tokens:
48+
49+
### URL placeholders
50+
51+
Name | Type | Required | Notes
52+
----------- | ------- | -------- | -----
53+
`{owner}` | string | no | The owner ID to get details for
54+
55+
The server should accept `{owner}` value with any casing.
56+
57+
For example, nuget.org's package details template looks like this:
58+
59+
```http
60+
https://www.nuget.org/profile/{owner}
61+
```
62+
63+
If the client implementation needs to display a link to the package details for NuGet.Versioning 4.3.0, it would
64+
produce the following URL and provide it to the user:
65+
66+
```http
67+
https://www.nuget.org/profiles/nuget
68+
```

0 commit comments

Comments
 (0)