NuGet Server-API
NuGet Server-API:et är en uppsättning HTTP-slutpunkter som kan användas för att ladda ned paket, hämta metadata, publicera nya paket och utföra de flesta andra åtgärder som är tillgängliga i de officiella NuGet-klienterna.
Det här API:et används av NuGet-klienten i Visual Studio, nuget.exeoch .NET CLI för att utföra NuGet-åtgärder som dotnet restore, söka i Visual Studio-användargränssnittet och nuget.exe push.
Observera i vissa fall att nuget.org har ytterligare krav som inte tillämpas av andra paketkällor. Dessa skillnader dokumenteras av nuget.org Protocols.
En enkel uppräkning och nedladdning av tillgängliga nuget.exe versioner finns i tools.json slutpunkten.
Om du implementerar en NuGet-paketlagringsplats kan du även läsa implementeringsguiden för ytterligare krav och rekommendationer.
Tjänstindex
Startpunkten för API:et är ett JSON-dokument på en välkänd plats. Det här dokumentet kallas tjänstindex. Tjänstindexets plats för nuget.org är https://api.nuget.org/v3/index.json.
Det här JSON-dokumentet innehåller en lista över resurser som ger olika funktioner och uppfyller olika användningsfall.
Klienter som stöder API:et bör acceptera en eller flera av dessa tjänstindex-URL:er som medel för att ansluta till respektive paketkällor.
Mer information om tjänstindexet finns i dess API-referens.
Versionshantering
API:et är version 3 av NuGets HTTP-protokoll. Det här protokollet kallas ibland för "V3 API". Dessa referensdokument refererar till den här versionen av protokollet helt enkelt som "API:et".
Schemaversionen för tjänstindex anges av egenskapen version i tjänstindexet. API:et kräver att versionssträngen har ett större versionsnummer 3. Eftersom icke-icke-bakåtkompatibla ändringar görs i tjänstindexschemat ökas versionssträngens delversion.
Äldre klienter (till exempel nuget.exe 2.x) stöder inte V3-API:et och stöder bara det äldre V2-API:et, som inte finns dokumenterat här.
NuGet V3-API:et namnges som sådant eftersom det är efterföljare till V2-API:et, som var det OData-baserade protokollet som implementerades av 2.x-versionen av den officiella NuGet-klienten. V3-API:et stöddes först av 3.0-versionen av den officiella NuGet-klienten och är fortfarande den senaste huvudprotokollversionen som stöds av NuGet-klienten, 4.0 och senare.
Icke-bakåtkompatibla protokolländringar har gjorts i API:et sedan det först släpptes.
Resurser och schema
-tjänstindexet beskriver en mängd olika resurser. Den aktuella uppsättningen resurser som stöds är följande:
| Resursnamn | Krävs | Beskrivning |
|---|---|---|
| katalog | Nej | Fullständig post för alla pakethändelser. |
| PackageBaseAddress | Ja | Hämta paketinnehåll (.nupkg). |
| PackageDetailsUriTemplate | Nej | Skapa en URL för att komma åt en webbsida med paketinformation. |
| PackagePublish | Ja | Skicka och ta bort (eller ta bort) paket. |
| ReadmeUriTemplate | Nej | Skapa en URL för att komma åt ett pakets README. |
| RegistrationsBaseUrl | Ja | Hämta paketmetadata. |
| ReportAbuseUriTemplate | Nej | Skapa en URL för att komma åt en webbplats för rapportmissbruk. |
| RepositorySignatures | Nej | Hämta certifikat som används för lagringsplatssignering. |
| SearchAutocompleteService | Nej | Identifiera paket-ID:er och versioner genom delsträng. |
| SearchQueryService | Ja | Filtrera och sök efter paket efter nyckelord. |
| SymbolPackagePublish | Nej | Push-symbolpaket. |
| VulnerabilityInfo | Nej | Paket med kända säkerhetsrisker. |
I allmänhet serialiseras alla icke-binära data som returneras av en API-resurs med JSON. Svarsschemat som returneras av varje resurs i tjänstindexet definieras individuellt för den resursen. Mer information om varje resurs finns i avsnitten ovan.
När protokollet utvecklas i framtiden kan nya egenskaper läggas till i JSON-svar. För att klienten ska vara framtidssäker bör implementeringen inte förutsätta att svarsschemat är slutgiltigt och inte kan innehålla extra data. Alla egenskaper som implementeringen inte förstår bör ignoreras.
Not
När en källa inte implementerar SearchAutocompleteService ska något beteende för automatisk komplettering inaktiveras korrekt. När ReportAbuseUriTemplate inte implementeras återgår den officiella NuGet-klienten till nuget.org:s url för rapportmissbruk (spåras av NuGet/Home#4924). Andra klienter kan välja att helt enkelt inte visa en url för rapportmissbruk för användaren.
Odokumenterade resurser på nuget.org
V3-tjänstindexet på nuget.org har vissa resurser som inte dokumenteras ovan. Det finns några orsaker till att du inte dokumenterar en resurs.
Först dokumenterar vi inte resurser som används som implementeringsinformation för nuget.org. SearchGalleryQueryService ingår i den här kategorin.
NuGetGallery använder den här resursen för att delegera vissa V2-frågor (OData) till vårt sökindex i stället för att använda databasen. Den här resursen introducerades av skalbarhetsskäl och är inte avsedd för extern användning.
För det andra dokumenterar vi inte resurser som aldrig har levererats i en RTM-version av den officiella klienten.
PackageDisplayMetadataUriTemplate och PackageVersionDisplayMetadataUriTemplate tillhör den här kategorin.
För det tredje dokumenterar vi inte resurser som är nära kopplade till V2-protokollet, som i sig är avsiktligt odokumenterat. Den LegacyGallery resursen tillhör den här kategorin. Med den här resursen kan ett V3-tjänstindex peka på en motsvarande V2-käll-URL. Den här resursen stöder nuget.exe list.
Om en resurs inte dokumenteras här vi starkt rekommenderar att du inte är beroende av dem. Vi kan ta bort eller ändra beteendet för dessa odokumenterade resurser som kan bryta implementeringen på oväntade sätt.
Tidsstämplar
Alla tidsstämplar som returneras av API:et är UTC eller anges på annat sätt med ISO 8601 representation.
HTTP-metoder
| Verb | Använda |
|---|---|
| FÅ | Utför en skrivskyddad åtgärd som vanligtvis hämtar data. |
| HUVUD | Hämtar svarshuvudena för motsvarande GET begäran. |
| STÄLLA | Skapar en resurs som inte finns eller uppdaterar den om den finns. Vissa resurser kanske inte stöder uppdatering. |
| TA BORT | Tar bort eller avlistar en resurs. |
HTTP-statuskoder
| Kod | Beskrivning |
|---|---|
| 200 | Lyckades och det finns en svarstext. |
| 201 | Lyckades och resursen skapades. |
| 202 | Begäran har godkänts, men en del arbete kan fortfarande vara ofullständigt och slutföras asynkront. |
| 204 | Lyckades, men det finns ingen svarstext. |
| 301 | En permanent omdirigering. |
| 302 | En tillfällig omdirigering. |
| 400 | Parametrarna i URL:en eller i begärandetexten är inte giltiga. |
| 401 | De angivna autentiseringsuppgifterna är ogiltiga. |
| 403 | Åtgärden tillåts inte med de angivna autentiseringsuppgifterna. |
| 404 | Den begärda resursen finns inte. |
| 409 | Begäran står i konflikt med en befintlig resurs. |
| 500 | Tjänsten har påträffat ett oväntat fel. |
| 503 | Tjänsten är inte tillgänglig för tillfället. |
Alla GET begäran som görs till en API-slutpunkt kan returnera en HTTP-omdirigering (301 eller 302). Klienter bör hantera sådana omdirigeringar korrekt genom att observera Location-huvudet och utfärda en efterföljande GET. Dokumentation om specifika slutpunkter kommer inte uttryckligen att ange var omdirigeringar kan användas.
När det gäller en statuskod på 500 nivåer kan klienten implementera en rimlig mekanism för återförsök. Den officiella NuGet-klienten försöker igen tre gånger när det uppstår statuskod på 500 nivåer eller TCP/DNS-fel.
HTTP-begärandehuvuden
| Namn | Beskrivning |
|---|---|
| X-NuGet-ApiKey | Information om hur du pushar och tar bort finns i PackagePublish resurs |
| X-NuGet-Client-Version |
Inaktuell och ersatt av X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Krävs i vissa fall endast på nuget.org, se nuget.org protokoll |
| X-NuGet-Session-Id | Valfritt. NuGet-klienter v4.7+ identifierar HTTP-begäranden som ingår i samma NuGet-klientsession. |
X-NuGet-Session-Id har ett enda värde för alla åtgärder som rör en enskild återställning i PackageReference. För andra scenarier som automatisk komplettering och packages.config återställning kan det finnas flera olika sessions-ID på grund av hur koden räknas in.
Autentisering
Autentiseringen är upp till den paketkällaimplementering som ska definieras. För nuget.org kräver endast den PackagePublish resursen autentisering via ett särskilt API-nyckelhuvud. Mer information finns i PackagePublish resurs.