Interfejs API serwera NuGet
Interfejs API serwera NuGet to zestaw punktów końcowych HTTP, które mogą służyć do pobierania pakietów, pobierania metadanych, publikowania nowych pakietów i wykonywania większości innych operacji dostępnych w oficjalnych klientach NuGet.
Ten interfejs API jest używany przez klienta NuGet w programie Visual Studio, nuget.exe i interfejsie wiersza polecenia platformy .NET do wykonywania operacji NuGet, takich jak dotnet restore, wyszukiwanie w interfejsie użytkownika programu Visual Studio i nuget.exe push.
Należy pamiętać, że w niektórych przypadkach nuget.org ma dodatkowe wymagania, które nie są wymuszane przez inne źródła pakietów. Te różnice są udokumentowane przez protokoły nuget.org.
Aby uzyskać proste wyliczenie i pobieranie dostępnych wersji nuget.exe, zobacz punkt końcowy tools.json .
Jeśli implementujesz repozytorium pakietów NuGet, zapoznaj się również z przewodnikiem implementacji, aby uzyskać dodatkowe wymagania i zalecenia.
Indeks usług
Punktem wejścia interfejsu API jest dokument JSON w dobrze znanej lokalizacji. Ten dokument jest nazywany indeksem usługi. Lokalizacja indeksu usługi dla nuget.org to https://api.nuget.org/v3/index.json.
Ten dokument JSON zawiera listę zasobów , które zapewniają różne funkcje i spełniają różne przypadki użycia.
Klienci, którzy obsługują interfejs API, powinni zaakceptować co najmniej jeden z tych adresów URL indeksu usługi jako sposób nawiązywania połączenia z odpowiednimi źródłami pakietów.
Aby uzyskać więcej informacji na temat indeksu usługi, zobacz dokumentację interfejsu API.
Wersje
Interfejs API jest w wersji 3 protokołu HTTP nuGet. Ten protokół jest czasami nazywany "interfejsem API w wersji 3". Te dokumenty referencyjne będą odwoływać się do tej wersji protokołu po prostu jako "interfejs API".
Wersja schematu indeksu usługi jest wskazywana przez version właściwość w indeksie usługi. Interfejs API nakazuje, aby ciąg wersji miał numer wersji głównej .3 W miarę wprowadzania zmian powodujących niezgodność w schemacie indeksu usługi wersja pomocnicza ciągu wersji zostanie zwiększona.
Starsi klienci (na przykład nuget.exe 2.x) nie obsługują interfejsu API w wersji 3 i obsługują tylko starszy interfejs API w wersji 2, który nie został opisany w tym miejscu.
Interfejs API NuGet v3 jest nazwany jako taki, ponieważ jest następcą interfejsu API w wersji 2, który był protokołem opartym na protokole OData zaimplementowanym przez wersję 2.x oficjalnego klienta NuGet. Interfejs API w wersji 3 został po raz pierwszy obsługiwany przez wersję 3.0 oficjalnego klienta NuGet i jest nadal najnowszą główną wersją protokołu obsługiwaną przez klienta NuGet, 4.0 i nowszego.
Zmiany protokołu powodujące niezgodność zostały wprowadzone w interfejsie API od czasu jej pierwszego wydania.
Zasoby i schemat
Indeks usługi opisuje różne zasoby. Bieżący zestaw obsługiwanych zasobów jest następujący:
| Nazwa zasobu | Wymagania | opis |
|---|---|---|
| Katalog | nie | Pełny rekord wszystkich zdarzeń pakietu. |
| PackageBaseAddress | tak | Pobierz zawartość pakietu (nupkg). |
| PackageDetailsUriTemplate | nie | Konstruowanie adresu URL w celu uzyskania dostępu do strony sieci Web szczegółów pakietu. |
| PackagePublish | tak | Wypychanie i usuwanie (lub usuwanie) pakietów. |
| RejestracjeBaseUrl | tak | Pobieranie metadanych pakietu. |
| ReportAbuseUriTemplate | nie | Skonstruuj adres URL umożliwiający dostęp do strony internetowej nadużyć w raporcie. |
| RepositorySignatures | nie | Pobierz certyfikaty używane do podpisywania repozytorium. |
| SearchAutocompleteService | nie | Odnajdź identyfikatory i wersje pakietów według podciągów. |
| SearchQueryService | tak | Filtruj i wyszukuj pakiety według słowa kluczowego. |
| SymbolPackagePublish | nie | Wypychanie pakietów symboli. |
| VulnerabilityInfo | nie | Pakiety ze znanymi lukami w zabezpieczeniach. |
Ogólnie rzecz biorąc, wszystkie dane niebinarne zwracane przez zasób interfejsu API są serializowane przy użyciu formatu JSON. Schemat odpowiedzi zwracany przez każdy zasób w indeksie usługi jest definiowany indywidualnie dla tego zasobu. Aby uzyskać więcej informacji na temat każdego zasobu, zobacz tematy wymienione powyżej.
W przyszłości, w miarę rozwoju protokołu, nowe właściwości mogą zostać dodane do odpowiedzi JSON. Aby klient był odporny na przyszłość, implementacja nie powinna zakładać, że schemat odpowiedzi jest końcowy i nie może zawierać dodatkowych danych. Wszystkie właściwości, których implementacja nie rozumie, powinny być ignorowane.
Uwaga
Jeśli źródło nie implementuje SearchAutocompleteService żadnego zachowania autouzupełniania, powinno być bezpiecznie wyłączone. Gdy ReportAbuseUriTemplate nie zostanie zaimplementowany, oficjalny klient NuGet powraca do adresu URL nadużyć raportu nuget.org (śledzony przez NuGet/Home#4924). Inni klienci mogą zdecydować się po prostu nie pokazywać użytkownikowi adresu URL nadużyć w raporcie.
Zasoby nieudokumentowane w usłudze nuget.org
Indeks usługi w wersji 3 nuget.org zawiera pewne zasoby, które nie zostały udokumentowane powyżej. Istnieje kilka powodów, dla których nie można udokumentować zasobu.
Najpierw nie dokumentujemy zasobów używanych jako szczegóły implementacji nuget.org. Należy SearchGalleryQueryService do tej kategorii. Narzędzie NuGetGallery używa tego zasobu do delegowania niektórych zapytań OData (V2) do naszego indeksu wyszukiwania zamiast używania bazy danych. Ten zasób został wprowadzony ze względu na skalowalność i nie jest przeznaczony do użytku zewnętrznego.
Po drugie, nie dokumentujemy zasobów, które nigdy nie zostały wysłane w wersji RTM oficjalnego klienta.
PackageDisplayMetadataUriTemplate i PackageVersionDisplayMetadataUriTemplate należy do tej kategorii.
Po trzecie, nie dokumentujemy zasobów ściśle powiązanych z protokołem V2, który jest celowo nieudokumentowany. Zasób LegacyGallery należy do tej kategorii. Ten zasób umożliwia indeksowi usługi w wersji 3 wskazanie odpowiedniego źródłowego adresu URL wersji 2. Ten zasób obsługuje element nuget.exe list.
Jeśli zasób nie jest udokumentowany w tym miejscu, zdecydowanie zalecamy, aby nie brać na nich zależności. Możemy usunąć lub zmienić zachowanie tych nieudokumentowanych zasobów, co może spowodować awarię implementacji w nieoczekiwany sposób.
Znaczniki czasu
Wszystkie znaczniki czasu zwracane przez interfejs API są utc lub w inny sposób określone przy użyciu reprezentacji ISO 8601 .
Metody HTTP
| Czasownik | Używanie |
|---|---|
| GET | Wykonuje operację tylko do odczytu, zazwyczaj pobiera dane. |
| HEAD | Pobiera nagłówki odpowiedzi dla odpowiedniego GET żądania. |
| ODŁÓŻ | Tworzy zasób, który nie istnieje lub, jeśli istnieje, aktualizuje go. Niektóre zasoby mogą nie obsługiwać aktualizacji. |
| DELETE | Usuwa lub usuwa listę zasobu. |
Kody stanu HTTP
| Kod | opis |
|---|---|
| 200 | Powodzenie i istnieje treść odpowiedzi. |
| 201 | Powodzenie i utworzono zasób. |
| 202 | Żądanie zostało zaakceptowane, ale niektóre prace mogą być nadal niekompletne i ukończone asynchronicznie. |
| 204 | Sukces, ale nie ma treści odpowiedzi. |
| 301 | Trwałe przekierowanie. |
| 302 | Tymczasowe przekierowanie. |
| 400 | Parametry w adresie URL lub w treści żądania są nieprawidłowe. |
| 401 | Podane poświadczenia są nieprawidłowe. |
| 403 | Akcja nie jest dozwolona, biorąc pod uwagę podane poświadczenia. |
| 404 | Żądany zasób nie istnieje. |
| 409 | Żądanie powoduje konflikt z istniejącym zasobem. |
| 500 | Usługa napotkała nieoczekiwany błąd. |
| 503 | Usługa jest tymczasowo niedostępna. |
Każde GET żądanie skierowane do punktu końcowego interfejsu API może zwrócić przekierowanie HTTP (301 lub 302). Klienci powinni bezpiecznie obsługiwać takie przekierowania, obserwując nagłówek i wydając Location kolejne GET. Dokumentacja dotycząca określonych punktów końcowych nie będzie jawnie określać, gdzie mogą być używane przekierowania.
W przypadku kodu stanu na poziomie 500 klient może zaimplementować rozsądny mechanizm ponawiania prób. Oficjalny klient NuGet ponawia próbę trzy razy podczas napotkania dowolnego kodu stanu na poziomie 500 lub błędu TCP/DNS.
Nagłówki żądań HTTP
| Nazwa/nazwisko | opis |
|---|---|
| X-NuGet-ApiKey | Wymagane do wypychania i usuwania, zobacz PackagePublish zasób |
| X-NuGet-Client-Version | Przestarzałe i zastąpione przez X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Wymagane w niektórych przypadkach tylko w nuget.org, zobacz protokoły nuget.org |
| X-NuGet-Session-Id | Opcjonalne. Klienci NuGet w wersji 4.7 lub nowszej identyfikują żądania HTTP będące częścią tej samej sesji klienta NuGet. |
Element X-NuGet-Session-Id ma pojedynczą wartość dla wszystkich operacji związanych z pojedynczym przywracaniem w programie PackageReference. W przypadku innych scenariuszy, takich jak autouzupełnianie i packages.config przywracanie, może istnieć kilka różnych identyfikatorów sesji ze względu na faktorowany kod.
Uwierzytelnianie
Uwierzytelnianie jest pozostawione do implementacji źródła pakietu do zdefiniowania. W przypadku nuget.org tylko PackagePublish zasób wymaga uwierzytelniania za pośrednictwem specjalnego nagłówka klucza interfejsu API. Aby uzyskać szczegółowe informacje, zobacz PackagePublish zasób .