From b8de56ddc023ec1dbfe00be7ccefa39704907e08 Mon Sep 17 00:00:00 2001 From: Martin Ruiz Date: Mon, 15 Apr 2024 10:35:28 -0700 Subject: [PATCH 1/5] Add API docs for owners template resource --- docs/TOC.md | 1 + docs/api/overview.md | 1 + docs/api/owner-details-template-resource.md | 68 +++++++++++++++++++++ 3 files changed, 70 insertions(+) create mode 100644 docs/api/owner-details-template-resource.md diff --git a/docs/TOC.md b/docs/TOC.md index e54fa2bf5..bfa3f6c7b 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -125,6 +125,7 @@ #### [Catalog](api/catalog-resource.md) #### [Package content](api/package-base-address-resource.md) #### [Package details URL](api/package-details-template-resource.md) +#### [Owner URL](api/package-owner-template-resource.md) #### [Package metadata](api/registration-base-url-resource.md) #### [Push and delete](api/package-publish-resource.md) #### [Push symbol packages](api/symbol-package-publish-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..f8450d07c --- /dev/null +++ b/docs/api/owner-details-template-resource.md @@ -0,0 +1,68 @@ +--- +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 server should accept `{owner}` value with any casing. + +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 +``` From 7d33f49743526a9840b7b75c5ac6bdb1f7fa06a2 Mon Sep 17 00:00:00 2001 From: Martin Ruiz Date: Wed, 17 Apr 2024 10:58:50 -0700 Subject: [PATCH 2/5] order links --- docs/TOC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TOC.md b/docs/TOC.md index bfa3f6c7b..5ba7beedd 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -123,9 +123,9 @@ ### Resources #### [Autocomplete](api/search-autocomplete-service-resource.md) #### [Catalog](api/catalog-resource.md) +#### [Owner URL](api/package-owner-template-resource.md) #### [Package content](api/package-base-address-resource.md) #### [Package details URL](api/package-details-template-resource.md) -#### [Owner URL](api/package-owner-template-resource.md) #### [Package metadata](api/registration-base-url-resource.md) #### [Push and delete](api/package-publish-resource.md) #### [Push symbol packages](api/symbol-package-publish-resource.md) From d2d7f174eacc76b1db326ecbff361801dbef756b Mon Sep 17 00:00:00 2001 From: Martin Ruiz Date: Wed, 17 Apr 2024 10:59:44 -0700 Subject: [PATCH 3/5] update documentation path --- docs/TOC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TOC.md b/docs/TOC.md index 5ba7beedd..7355ead22 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -123,7 +123,7 @@ ### Resources #### [Autocomplete](api/search-autocomplete-service-resource.md) #### [Catalog](api/catalog-resource.md) -#### [Owner URL](api/package-owner-template-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) From 786f6e2be997ce0511aaeeb35c31759c12db370e Mon Sep 17 00:00:00 2001 From: Martin Ruiz Date: Thu, 18 Apr 2024 18:23:16 -0700 Subject: [PATCH 4/5] improve documentation for oweners template --- docs/api/owner-details-template-resource.md | 26 ++++++++++----------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/api/owner-details-template-resource.md b/docs/api/owner-details-template-resource.md index f8450d07c..6f351882f 100644 --- a/docs/api/owner-details-template-resource.md +++ b/docs/api/owner-details-template-resource.md @@ -10,9 +10,8 @@ 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. +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). @@ -27,20 +26,17 @@ 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. +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. +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. +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. @@ -52,7 +48,10 @@ Name | Type | Required | Notes ----------- | ------- | -------- | ----- `{owner}` | string | no | The owner ID to get details for -The server should accept `{owner}` value with any casing. +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: @@ -60,8 +59,7 @@ For example, nuget.org's package details template looks like this: 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: +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 From e740e0090b92d1cf9de05cd2e5aed97f30665d84 Mon Sep 17 00:00:00 2001 From: Martin Ruiz Date: Tue, 23 Apr 2024 14:48:16 -0700 Subject: [PATCH 5/5] improve doc --- docs/api/package-details-template-resource.md | 37 ++++++++----------- 1 file changed, 16 insertions(+), 21 deletions(-) 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