Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add API docs for owners' template resource. #3282

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Add API docs for owners' template resource. #3282

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b8de56d
Add API docs for owners template resource
martinrrm Apr 15, 2024
7d33f49
order links
martinrrm Apr 17, 2024
d2d7f17
update documentation path
martinrrm Apr 17, 2024
786f6e2
improve documentation for oweners template
martinrrm Apr 19, 2024
e740e00
improve doc
martinrrm Apr 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/TOC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
1 change: 1 addition & 0 deletions docs/api/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
66 changes: 66 additions & 0 deletions docs/api/owner-details-template-resource.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doc LGTM.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
It is possible for a client to build a URL that can be used by the user to see a package owner's profile 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure... maybe scratch this for now? As far as I know, nuget.org's owner profile pages are just a profile photo and listings of packages owned by that individual. They don't really add details... or can they?

From my spec's perspective, the purpose is to get some reassurance that the owner is really the owner I expect, by looking at their other published packages on this package source.


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hadn't considered an optional parameter. Is the idea that every owner link would actually just point to the Gallery?.
This may help package sources to temporarily implement this feature by pointing their owner details hyperlink to some landing page (like Gallery?).
/cc @joelverhagen for additional thoughts

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are two kinds of required that matter I think: 1) the client rejects or errors out when no {owner} parameter is found and 2) we say it's required in the docs because we think it should really be there, but we make no effort to enforce it in the client.

I think having the same URL for every owner (i.e. no {owner} token) is a bad user experience but I don't know how to best surface that error in client.

In short, I think saying required = yes in the docs as a description of intent is okay even if client does no validation on this. required = no gives the wrong intent

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Required yes" sounds good to me.

I agree that it's a bad user experience to have identical links for all owners, but we could leave that up to the package source. I wanted to know whether to add validation in Client in my work in progress. I will not and just allow it to get the same repeated URL for each owner.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 Sure, no manipulation of casing on Client


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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is talking about package details template, but the example is for an owner details template.


```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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example appears to be from the package details template.


```http
https://www.nuget.org/profiles/nuget
```