NuGet Server-API
De NuGet Server-API is een set HTTP-eindpunten die kunnen worden gebruikt voor het downloaden van pakketten, het ophalen van metagegevens, het publiceren van nieuwe pakketten en het uitvoeren van de meeste andere bewerkingen die beschikbaar zijn in de officiële NuGet-clients.
Deze API wordt gebruikt door de NuGet-client in Visual Studio, nuget.exeen de .NET CLI om NuGet-bewerkingen uit te voeren, zoals dotnet restore, zoeken in de Visual Studio-gebruikersinterface en nuget.exe push.
Houd er rekening mee dat nuget.org aanvullende vereisten heeft die niet worden afgedwongen door andere pakketbronnen. Deze verschillen worden gedocumenteerd door de nuget.org Protocollen.
Zie het tools.json-eindpunt voor een eenvoudige opsomming en het downloaden van beschikbare nuget.exe versies.
Als u een NuGet-pakketopslagplaats implementeert, raadpleegt u ook de implementatiehandleiding voor aanvullende vereisten en aanbevelingen.
Service-index
Het toegangspunt voor de API is een JSON-document op een bekende locatie. Dit document wordt de service-indexgenoemd. De locatie van de service-index voor nuget.org is https://api.nuget.org/v3/index.json.
Dit JSON-document bevat een lijst met resources die verschillende functionaliteit bieden en voldoen aan verschillende use cases.
Clients die de API ondersteunen, moeten een of meer van deze serviceindex-URL's accepteren als het middel om verbinding te maken met de respectieve pakketbronnen.
Zie api-verwijzingvoor meer informatie over de serviceindex.
Versiebeheer
De API is versie 3 van het HTTP-protocol van NuGet. Dit protocol wordt ook wel 'de V3-API' genoemd. Deze referentiedocumenten verwijzen naar deze versie van het protocol als 'de API'.
De schemaversie van de serviceindex wordt aangegeven door de eigenschap version in de serviceindex. De API vereist dat de versietekenreeks een groot versienummer van 3heeft. Als er niet-belangrijke wijzigingen worden aangebracht in het indexschema van de service, wordt de secundaire versie van de versietekenreeks verhoogd.
Oudere clients (zoals nuget.exe 2.x) bieden geen ondersteuning voor de V3-API en ondersteunen alleen de oudere V2-API, die hier niet wordt beschreven.
De NuGet V3-API heet als zodanig omdat dit de opvolger is van de V2-API, het OData-protocol dat is geïmplementeerd door de 2.x-versie van de officiële NuGet-client. De V3-API werd eerst ondersteund door de 3.0-versie van de officiële NuGet-client en is nog steeds de nieuwste primaire protocolversie die wordt ondersteund door de NuGet-client, 4.0 en hoger.
Niet-belangrijke protocolwijzigingen zijn aangebracht in de API sinds deze voor het eerst werd uitgebracht.
Resources en schema
In de service-index worden verschillende resources beschreven. De huidige set ondersteunde resources is als volgt:
| Resourcenaam | Vereist | Beschrijving |
|---|---|---|
| Catalogus | Nee | Volledige record van alle pakketevenementen. |
| PackageBaseAddress- | ja | Pakketinhoud ophalen (.nupkg). |
| PackageDetailsUriTemplate- | Nee | Maak een URL voor toegang tot een webpagina met pakketdetails. |
| PackagePublish | ja | Pakketten pushen en verwijderen (of uit de lijst verwijderen). |
| ReadmeUriTemplate- | Nee | Maak een URL voor toegang tot het LEESMIJ-bestand van een pakket. |
| RegistrationsBaseUrl- | ja | Haal pakketmetagegevens op. |
| ReportAbuseUriTemplate- | Nee | Maak een URL voor toegang tot een webpagina met misbruik van rapporten. |
| RepositorySignatures | Nee | Certificaten ophalen die worden gebruikt voor ondertekening van opslagplaatsen. |
| SearchAutocompleteService | Nee | Ontdek pakket-id's en versies door middel van subtekenreeksen. |
| SearchQueryService | ja | Filteren en zoeken naar pakketten op trefwoord. |
| SymbolPackagePublish- | Nee | Symboolpakketten pushen. |
| VulnerabilityInfo- | Nee | Pakketten met bekende beveiligingsproblemen. |
Over het algemeen worden alle niet-binaire gegevens die worden geretourneerd door een API-resource geserialiseerd met behulp van JSON. Het antwoordschema dat door elke resource in de serviceindex wordt geretourneerd, wordt afzonderlijk gedefinieerd voor die resource. Zie de bovenstaande onderwerpen voor meer informatie over elke resource.
In de toekomst, naarmate het protocol zich ontwikkelt, kunnen nieuwe eigenschappen worden toegevoegd aan JSON-antwoorden. Om de client toekomstbestendig te maken, mag de implementatie er niet van uitgaan dat het antwoordschema definitief is en geen extra gegevens kan bevatten. Alle eigenschappen die de implementatie niet begrijpt, moeten worden genegeerd.
Notitie
Wanneer een bron geen SearchAutocompleteService gedrag voor automatisch aanvullen niet correct moet worden uitgeschakeld. Wanneer ReportAbuseUriTemplate niet is geïmplementeerd, valt de officiële NuGet-client terug op de misbruik-URL van nuget.org (bijgehouden door NuGet/Home#4924). Andere clients kunnen ervoor kiezen om simpelweg geen misbruik-URL voor het rapport aan de gebruiker weer te geven.
Niet-gedocumenteerde resources op nuget.org
De V3-serviceindex op nuget.org bevat enkele resources die hierboven niet zijn gedocumenteerd. Er zijn enkele redenen om een resource niet te documenteren.
Eerst documenteer we geen resources die worden gebruikt als implementatiedetails van nuget.org. De SearchGalleryQueryService valt in deze categorie.
NuGetGallery deze resource gebruikt om sommige V2-query's (OData) te delegeren aan onze zoekindex in plaats van de database te gebruiken. Deze resource is geïntroduceerd om schaalbaarheidsredenen en is niet bedoeld voor extern gebruik.
Ten tweede documenteer we geen resources die nooit zijn verzonden in een RTM-versie van de officiële client.
PackageDisplayMetadataUriTemplate en PackageVersionDisplayMetadataUriTemplate vallen in deze categorie.
Ten derde documenteert u geen resources die nauw zijn gekoppeld aan het V2-protocol, dat zelf opzettelijk niet is gedocumenteerd. De LegacyGallery resource valt in deze categorie. Met deze resource kan een V3-serviceindex verwijzen naar een bijbehorende V2-bron-URL. Deze resource ondersteunt de nuget.exe list.
Als een resource hier niet wordt gedocumenteerd, we sterk raden u aan deze resources niet afhankelijk te maken. We kunnen het gedrag van deze niet-gedocumenteerde resources verwijderen of wijzigen, waardoor uw implementatie op onverwachte manieren kan worden onderbroken.
Tijdstempels
Alle tijdstempels die door de API worden geretourneerd, zijn UTC of worden op een andere manier opgegeven met behulp van ISO 8601 weergave.
HTTP-methoden
| Werkwoord | Gebruiken |
|---|---|
| TOEVOEGEN | Voert een alleen-lezenbewerking uit, meestal worden gegevens opgehaald. |
| HOOFD | Haalt de antwoordheaders op voor de bijbehorende GET aanvraag. |
| ZETTEN | Hiermee maakt u een resource die niet bestaat of, als deze bestaat, wordt deze bijgewerkt. Sommige resources ondersteunen mogelijk geen update. |
| VERWIJDEREN | Hiermee verwijdert u een resource of verwijdert u deze uit de lijst. |
HTTP-statuscodes
| Code | Beschrijving |
|---|---|
| 200 | Succes, en er is een antwoordtekst. |
| 201 | Geslaagd en de resource is gemaakt. |
| 202 | Geslaagd, de aanvraag is geaccepteerd, maar sommige werkzaamheden zijn mogelijk nog steeds onvolledig en asynchroon voltooid. |
| 204 | Succes, maar er is geen antwoordtekst. |
| 301 | Een permanente omleiding. |
| 302 | Een tijdelijke omleiding. |
| 400 | De parameters in de URL of in de aanvraagbody zijn niet geldig. |
| 401 | De opgegeven referenties zijn ongeldig. |
| 403 | De actie is niet toegestaan op basis van de opgegeven referenties. |
| 404 | De aangevraagde resource bestaat niet. |
| 409 | De aanvraag conflicteert met een bestaande resource. |
| 500 | Er is een onverwachte fout opgetreden in de service. |
| 503 | De service is tijdelijk niet beschikbaar. |
Elke GET aanvraag naar een API-eindpunt kan een HTTP-omleiding (301 of 302) retourneren. Clients moeten dergelijke omleidingen correct verwerken door de Location header te observeren en een volgende GETuit te geven. Documentatie over specifieke eindpunten wordt niet expliciet aangeroepen waar omleidingen kunnen worden gebruikt.
In het geval van een statuscode op 500 niveau kan de client een redelijk mechanisme voor opnieuw proberen implementeren. De officiële NuGet-client probeert drie keer opnieuw wanneer er statuscode op 500-niveau of TCP/DNS-fout optreedt.
HTTP-aanvraagheaders
| Naam | Beschrijving |
|---|---|
| X-NuGet-ApiKey | Zie PackagePublish resource vereist voor pushen en verwijderen |
| X-NuGet-Client-Version |
afgeschafte en vervangen door X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Zie nuget.org protocollen in bepaalde gevallen alleen voor nuget.org |
| X-NuGet-Session-Id | Optionele. NuGet-clients v4.7+ identificeren HTTP-aanvragen die deel uitmaken van dezelfde NuGet-clientsessie. |
De X-NuGet-Session-Id heeft één waarde voor alle bewerkingen die betrekking hebben op één herstelbewerking in PackageReference. Voor andere scenario's, zoals automatisch aanvullen en packages.config herstellen, kunnen er verschillende sessie-id's zijn vanwege de manier waarop de code wordt gerekend.
Authenticatie
Verificatie wordt overgelaten aan de implementatie van de pakketbron om te definiëren. Voor nuget.org vereist alleen de PackagePublish-resource verificatie via een speciale API-sleutelheader. Zie PackagePublish resource voor meer informatie.