diff --git a/docs/TOC.md b/docs/TOC.md index e54fa2bf5..7355ead22 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -123,6 +123,7 @@ ### Resources #### [Autocomplete](api/search-autocomplete-service-resource.md) #### [Catalog](api/catalog-resource.md) +#### [Owner URL](api/owner-details-template-resource.md) #### [Package content](api/package-base-address-resource.md) #### [Package details URL](api/package-details-template-resource.md) #### [Package metadata](api/registration-base-url-resource.md) diff --git a/docs/api/overview.md b/docs/api/overview.md index 2d15e8766..1915d7b2b 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -60,6 +60,7 @@ Resource name | Required [Catalog](catalog-resource.md) | no | Full record of all package events. [PackageBaseAddress](package-base-address-resource.md) | yes | Get package content (.nupkg). [PackageDetailsUriTemplate](package-details-template-resource.md) | no | Construct a URL to access a package details web page. +[OwnerDetailsUriTemplate](owner-details-template-resource.md) | no | Construct a URL to access an owner web page. [PackagePublish](package-publish-resource.md) | yes | Push and delete (or unlist) packages. [RegistrationsBaseUrl](registration-base-url-resource.md) | yes | Get package metadata. [ReportAbuseUriTemplate](report-abuse-resource.md) | no | Construct a URL to access a report abuse web page. diff --git a/docs/api/owner-details-template-resource.md b/docs/api/owner-details-template-resource.md new file mode 100644 index 000000000..6f351882f --- /dev/null +++ b/docs/api/owner-details-template-resource.md @@ -0,0 +1,66 @@ +--- +title: Owner URL Template, NuGet API +description: The Owner URL template allows clients to display in their UI a web link +author: martinrrm +ms.author: mruizmares +ms.date: 4/15/2024 +ms.topic: reference +ms.reviewer: +--- + +# Owner URL template + +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 browser. +This is useful when a package source wants to show additional information about an owner that may not fit within the scope of what the NuGet client application shows. + +The resource used for building this URL is the `OwnerDetailsUriTemplate` resource found in the +[service index](service-index.md). + +## Versioning + +The following `@type` values are used: + +@type value | Notes +------------------------------- | ----- +OwnerDetailsUriTemplate/6.11.0 | The initial release + +## URL template + +The URL for the following API is the value of the `@id` property associated with one of the aforementioned resource `@type` values. + +## HTTP methods + +Although the client is not intended to make requests to the owner URL on behalf of the user, the web page should support the `GET` method to allow a clicked URL to be easily opened in a web browser. + +## Construct the URL + +Given a known owner ID, the client implementation can construct a URL used to access a web interface. +The client implementation should display this constructed URL (or clickable link) to the user allowing them to open a web browser to the URL and to learn more about the owner. +The contents of the owner page is determined by the server implementation. + +The URL must be an absolute URL and the scheme (protocol) must be HTTPS. + +The value of the `@id` in the service index is a URL string containing any of the following placeholder tokens: + +### URL placeholders + +Name | Type | Required | Notes +----------- | ------- | -------- | ----- +`{owner}` | string | no | The owner ID to get details for + +The casing requirements of {owner} should be defined by the package source. +The client should retain the casing of the username in whatever form it was found in other API responses or in the package repository signature. + +NuGet.org treats owner usernames in a case insensitive manner but not all package source may have this flexibility. + +For example, nuget.org's package details template looks like this: + +```http +https://www.nuget.org/profile/{owner} +``` + +If the client implementation needs to display a link to the package details for NuGet.Versioning 4.3.0, it would produce the following URL and provide it to the user: + +```http +https://www.nuget.org/profiles/nuget +``` diff --git a/docs/api/package-details-template-resource.md b/docs/api/package-details-template-resource.md index b2c7928f3..59310e9a0 100644 --- a/docs/api/package-details-template-resource.md +++ b/docs/api/package-details-template-resource.md @@ -25,27 +25,6 @@ The following `@type` values are used: ------------------------------- | ----- PackageDetailsUriTemplate/5.1.0 | The initial release -## URL template - -The URL for the following API is the value of the `@id` property associated with one of the aforementioned -resource `@type` values. - -## HTTP methods - -Although the client is not intended to make requests to the package details URL on behalf of the user, the web page -should support the `GET` method to allow a clicked URL to be easily opened in a web browser. - -## Construct the URL - -Given a known package ID and version, the client implementation can construct a URL used to access a web interface. The -client implementation should display this constructed URL (or clickable link) to the user allowing them to open a web -browser to the URL and to learn more about the package. The contents of the package details page is determined by the -server implementation. - -The URL must be an absolute URL and the scheme (protocol) must be HTTPS. - -The value of the `@id` in the service index is a URL string containing any of the following placeholder tokens: - ### URL placeholders Name | Type | Required | Notes @@ -70,3 +49,19 @@ produce the following URL and provide it to the user: ```http https://www.nuget.org/packages/NuGet.Versioning/4.3.0 ``` + +## Construct the URL + +Given a known package ID and version, the client implementation can construct a URL used to access a web interface. The +client implementation should display this constructed URL (or clickable link) to the user allowing them to open a web +browser to the URL and to learn more about the package. The contents of the package details page is determined by the +server implementation. + +The URL must be an absolute URL and the scheme (protocol) must be HTTPS. + +The value of the `@id` in the service index is a URL string containing any of the following placeholder tokens: + +## HTTP methods + +Although the client is not intended to make requests to the package details URL on behalf of the user, the web page +should support the `GET` method to allow a clicked URL to be easily opened in a web browser. \ No newline at end of file