NuGet Server API
NUGet Server API adalah sekumpulan titik akhir HTTP yang dapat digunakan untuk mengunduh paket, mengambil metadata, menerbitkan paket baru, dan melakukan sebagian besar operasi lain yang tersedia di klien NuGet resmi.
API ini digunakan oleh klien NuGet di Visual Studio, nuget.exe, dan .NET CLI untuk melakukan operasi NuGet seperti dotnet restore, cari di Visual Studio UI, dan nuget.exe push.
Perhatikan dalam beberapa kasus, nuget.org memiliki persyaratan tambahan yang tidak diberlakukan oleh sumber paket lain. Perbedaan ini didokumenkan oleh Protokol nuget.org.
Untuk enumerasi sederhana dan unduhan versi nuget.exe yang tersedia, lihat titik akhir tools.json.
Jika Anda menerapkan repositori paket NuGet, lihat juga panduan implementasi untuk persyaratan dan rekomendasi tambahan.
Indeks layanan
Titik masuk untuk API adalah dokumen JSON di lokasi terkenal. Dokumen ini disebut indeks layanan . Lokasi indeks layanan untuk nuget.org https://api.nuget.org/v3/index.json.
Dokumen JSON ini berisi daftar sumber daya yang menyediakan fungsionalitas yang berbeda dan memenuhi kasus penggunaan yang berbeda.
Klien yang mendukung API harus menerima satu atau beberapa URL indeks layanan ini sebagai sarana untuk menyambungkan ke sumber paket masing-masing.
Untuk informasi selengkapnya tentang indeks layanan, lihat referensi API-nya.
Penerapan versi
API adalah versi 3 dari protokol HTTP NuGet. Protokol ini terkadang disebut sebagai "API V3". Dokumen referensi ini akan merujuk ke versi protokol ini hanya sebagai "API."
Versi skema indeks layanan ditunjukkan oleh properti version dalam indeks layanan. API mengamanatkan bahwa string versi memiliki nomor versi utama 3. Karena perubahan yang tidak melanggar dilakukan pada skema indeks layanan, versi minor string versi akan ditingkatkan.
Klien lama (seperti nuget.exe 2.x) tidak mendukung API V3 dan hanya mendukung API V2 yang lebih lama, yang tidak didokumenkan di sini.
API NuGet V3 dinamai seperti itu karena merupakan penerus API V2, yang merupakan protokol berbasis OData yang diterapkan oleh versi 2.x dari klien NuGet resmi. API V3 pertama kali didukung oleh versi 3.0 dari klien NuGet resmi dan masih merupakan versi protokol utama terbaru yang didukung oleh klien NuGet, 4.0 dan seterangnya.
Perubahan protokol yang tidak melanggar telah dilakukan pada API sejak pertama kali dirilis.
Sumber daya dan skema
Indeks layanan menjelaskan berbagai sumber daya. Kumpulan sumber daya yang didukung saat ini adalah sebagai berikut:
| Nama sumber daya | Diperlukan | Deskripsi |
|---|---|---|
| Katalog | Tidak | Catatan lengkap semua peristiwa paket. |
| PackageBaseAddress | Ya | Dapatkan konten paket (.nupkg). |
| PackageDetailsUriTemplate | Tidak | Buat URL untuk mengakses halaman web detail paket. |
| PackagePublish | Ya | Dorong dan hapus (atau batalkan daftar) paket. |
| ReadmeUriTemplate | Tidak | Buat URL untuk mengakses README paket. |
| RegistrationsBaseUrl | Ya | Dapatkan metadata paket. |
| ReportAbuseUriTemplate | Tidak | Buat URL untuk mengakses halaman web penyalahgunaan laporan. |
| RepositoriSignatures | Tidak | Dapatkan sertifikat yang digunakan untuk penandatanganan repositori. |
| SearchAutocompleteService | Tidak | Temukan ID dan versi paket dengan substring. |
| SearchQueryService | Ya | Filter dan cari paket menurut kata kunci. |
| SymbolPackagePublish | Tidak | Mendorong paket simbol. |
| VulnerabilityInfo | Tidak | Paket dengan kerentanan yang diketahui. |
Secara umum, semua data non-biner yang dikembalikan oleh sumber daya API diserialisasikan menggunakan JSON. Skema respons yang dikembalikan oleh setiap sumber daya dalam indeks layanan didefinisikan secara individual untuk sumber daya tersebut. Untuk informasi selengkapnya tentang setiap sumber daya, lihat topik yang tercantum di atas.
Di masa depan, seiring berkembangnya protokol, properti baru dapat ditambahkan ke respons JSON. Agar klien menjadi bukti masa depan, implementasi tidak boleh berasumsi bahwa skema respons bersifat final dan tidak dapat menyertakan data tambahan. Semua properti yang tidak dipahami implementasi harus diabaikan.
Nota
Ketika sumber tidak menerapkan SearchAutocompleteService perilaku lengkapi otomatis apa pun harus dinonaktifkan dengan baik. Ketika ReportAbuseUriTemplate tidak diimplementasikan, klien NuGet resmi kembali ke URL penyalahgunaan laporan nuget.org (dilacak oleh NuGet/Home#4924). Klien lain dapat memilih untuk tidak hanya menampilkan URL penyalahgunaan laporan kepada pengguna.
Sumber daya yang tidak terdokumentasi pada nuget.org
Indeks layanan V3 pada nuget.org memiliki beberapa sumber daya yang tidak didokumenkan di atas. Ada beberapa alasan untuk tidak mendokumenkan sumber daya.
Pertama, kami tidak mendokumentasikan sumber daya yang digunakan sebagai detail implementasi nuget.org. SearchGalleryQueryService termasuk dalam kategori ini.
NuGetGallery menggunakan sumber daya ini untuk mendelegasikan beberapa kueri V2 (OData) ke indeks pencarian kami alih-alih menggunakan database. Sumber daya ini diperkenalkan karena alasan skalabilitas dan tidak ditujukan untuk penggunaan eksternal.
Kedua, kami tidak mendokumentasikan sumber daya yang tidak pernah dikirim dalam versi RTM klien resmi.
PackageDisplayMetadataUriTemplate dan PackageVersionDisplayMetadataUriTemplate termasuk dalam kategori ini.
Ketiga, kami tidak mendokumentasikan sumber daya yang digabungkan erat dengan protokol V2, yang sengaja tidak didokumentasikan. Sumber daya LegacyGallery termasuk dalam kategori ini. Sumber daya ini memungkinkan indeks layanan V3 untuk menunjuk ke URL sumber V2 yang sesuai. Sumber daya ini mendukung nuget.exe list.
Jika sumber daya tidak didokumenkan di sini, kami sangat menyarankan agar Anda tidak mengambil dependensi pada sumber daya tersebut. Kami dapat menghapus atau mengubah perilaku sumber daya yang tidak terdokumentasi ini yang dapat merusak implementasi Anda dengan cara yang tidak terduga.
Tanda waktu
Semua tanda waktu yang dikembalikan oleh API adalah UTC atau ditentukan lain menggunakan representasi ISO 8601.
Metode HTTP
| Kata kerja | Pakai |
|---|---|
| DAPAT | Melakukan operasi baca-saja, biasanya mengambil data. |
| KEPALA | Mengambil header respons untuk permintaan GET yang sesuai. |
| MELETAKKAN | Membuat sumber daya yang tidak ada atau, jika memang ada, memperbaruinya. Beberapa sumber daya mungkin tidak mendukung pembaruan. |
| MENGHAPUS | Menghapus atau membatalkan daftar sumber daya. |
Kode status HTTP
| Kode | Deskripsi |
|---|---|
| 200 | Sukses, dan ada isi respons. |
| 201 | Berhasil, dan sumber daya dibuat. |
| 202 | Berhasil, permintaan telah diterima tetapi beberapa pekerjaan mungkin masih tidak lengkap dan diselesaikan secara asinkron. |
| 204 | Sukses, tetapi tidak ada isi respons. |
| 301 | Pengalihan permanen. |
| 302 | Pengalihan sementara. |
| 400 | Parameter dalam URL atau di isi permintaan tidak valid. |
| 401 | Kredensial yang disediakan tidak valid. |
| 403 | Tindakan tidak diperbolehkan diberikan kredensial yang disediakan. |
| 404 | Sumber daya yang diminta tidak ada. |
| 409 | Permintaan bertentangan dengan sumber daya yang ada. |
| 500 | Layanan mengalami kesalahan tak terduga. |
| 503 | Layanan ini untuk sementara tidak tersedia. |
Setiap permintaan GET yang dibuat ke titik akhir API dapat mengembalikan pengalihan HTTP (301 atau 302). Klien harus dengan anggun menangani pengalihan tersebut dengan mengamati header Location dan mengeluarkan GETberikutnya. Dokumentasi mengenai titik akhir tertentu tidak akan secara eksplisit memanggil di mana pengalihan dapat digunakan.
Dalam kasus kode status tingkat 500, klien dapat menerapkan mekanisme coba lagi yang wajar. Klien NuGet resmi mencoba kembali tiga kali ketika mengalami kode status tingkat 500 atau kesalahan TCP/DNS.
Header permintaan HTTP
| Nama | Deskripsi |
|---|---|
| X-NuGet-ApiKey | Diperlukan untuk pendorongan dan penghapusan, lihat sumber dayaPackagePublish |
| X-NuGet-Client-Version |
Tidak digunakan lagi dan digantikan oleh X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Diperlukan dalam kasus tertentu hanya pada nuget.org, lihat protokol nuget.org |
| X-NuGet-Session-Id | Opsional . Klien NuGet v4.7+ mengidentifikasi permintaan HTTP yang merupakan bagian dari sesi klien NuGet yang sama. |
X-NuGet-Session-Id memiliki nilai tunggal untuk semua operasi yang terkait dengan satu pemulihan di PackageReference. Untuk skenario lain seperti pelengkapan otomatis dan pemulihan packages.config mungkin ada beberapa ID sesi yang berbeda karena bagaimana kode diperhitungkan.
Otentikasi
Autentikasi dibiarkan hingga implementasi sumber paket untuk ditentukan. Untuk nuget.org, hanya sumber daya PackagePublish yang memerlukan autentikasi melalui header kunci API khusus. Lihat sumber dayaPackagePublish untuk detailnya.