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

Jump to bottom

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 1 commit
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 @@ -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)
martinrrm marked this conversation as resolved.
Show resolved Hide resolved
#### [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)
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
68 changes: 68 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,68 @@
---
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. 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.
martinrrm marked this conversation as resolved.
Show resolved Hide resolved

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

Choose a reason for hiding this comment

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

I'm sorry, but I really don't understand what this sentence means, or what information this "URL template" section is trying to convey.

According to the docs style and voice guide: https://learn.microsoft.com/en-au/contribute/content/style-quick-start
the docs should be written in a casual voice, like a conversation, and use simple, easy to read sentences. I don't think this sentence/paragraph is doing that.

FWIW, I feel like this is a good place for the first example value. Reading the doc top down, it all feels a bit abstract and hard to pin down, until the examples in the last 3 lines of the docs. If there was an example here, early on in the docs page, I think it makes the rest of the docs more relatable.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Tbh I just copied from other documents that have the same section. @joelverhagen I don't see a lot of value in having this section in the documentation, do you think we should keep it? If so, how can we improve this section?

Copy link
Member

Choose a reason for hiding this comment

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

I don't feel strongly. Feel free to edit it according to @zivkan's suggestions. Sounds reasonable.


## 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 server should accept `{owner}` value with any casing.
martinrrm marked this conversation as resolved.
Show resolved Hide resolved

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:

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