API сервера NuGet
API NuGet Server — это набор конечных точек HTTP, которые можно использовать для скачивания пакетов, получения метаданных, публикации новых пакетов и выполнения большинства других операций, доступных в официальных клиентах NuGet.
Этот API используется клиентом NuGet в Visual Studio, nuget.exe и .NET CLI для выполнения таких операций NuGet, как dotnet restoreпоиск в пользовательском интерфейсе Visual Studio и nuget.exe push.
Обратите внимание, что в некоторых случаях nuget.org имеет дополнительные требования, которые не применяются другими источниками пакетов. Эти различия задокументированы протоколами nuget.org.
Простое перечисление и скачивание доступных версий nuget.exe см. в tools.json конечной точке.
Если вы реализуете репозиторий пакетов NuGet, ознакомьтесь с руководством по реализации дополнительных требований и рекомендаций.
Индекс службы
Точка входа для API — это документ JSON в известном расположении. Этот документ называется индексом службы. Расположение индекса службы для nuget.org https://api.nuget.org/v3/index.json.
Этот документ JSON содержит список ресурсов , которые предоставляют различные функциональные возможности и выполняют различные варианты использования.
Клиенты, поддерживающие API, должны принимать один или несколько URL-адрес индекса службы в качестве средства подключения к соответствующим источникам пакетов.
Дополнительные сведения об индексе службы см . в справочнике по API.
Управление версиями
API версии 3 протокола HTTP NuGet. Этот протокол иногда называется API версии 3. Эти справочные документы будут ссылаться на эту версию протокола просто как "API".
Версия схемы индекса службы указывается свойством version в индексе службы. API требует, чтобы строка версии представляла основной номер версии 3. Так как в схему индекса службы вносятся некритические изменения, дополнительный номер версии в строке версии увеличится.
Старые клиенты (например, nuget.exe 2.x) не поддерживают API версии 3 и поддерживают только старый API версии 2, который здесь не описан.
API NuGet версии 3 называется таким образом, так как он является преемником API версии 2, который был протоколом на основе OData, реализованным версией 2.x официального клиента NuGet. API версии 3 впервые поддерживается официальной версией клиента NuGet версии 3.0 и по-прежнему является последней основной версией протокола, поддерживаемой клиентом NuGet, 4.0 и в ней.
Неисключаемые изменения протокола были внесены в API после первого выпуска.
Ресурсы и схема
Индекс службы описывает различные ресурсы. Текущий набор поддерживаемых ресурсов выглядит следующим образом:
| Имя ресурса | Обязательное поле | Описание |
|---|---|---|
| Каталог | no | Полная запись всех событий пакета. |
| PackageBaseAddress | yes | Получение содержимого пакета (NUPKG). |
| PackageDetailsUriTemplate | no | Создайте URL-адрес для доступа к веб-странице сведений о пакете. |
| PackagePublish | yes | Отправка и удаление (или отмена списка) пакетов. |
| RegistrationsBaseUrl | yes | Получение метаданных пакета. |
| ReportAbuseUriTemplate | no | Создайте URL-адрес для доступа к веб-странице злоупотреблений отчетом. |
| РепозиторийSignatures | no | Получение сертификатов, используемых для подписи репозитория. |
| SearchAutocompleteService | no | Обнаружение идентификаторов пакетов и версий путем подстроки. |
| SearchQueryService | yes | Фильтрация и поиск пакетов по ключевое слово. |
| SymbolPackagePublish | no | Отправка пакетов символов. |
| УязвимостьInfo | no | Пакеты с известными уязвимостями. |
Как правило, все не двоичные данные, возвращаемые ресурсом API, сериализуются с помощью JSON. Схема ответа, возвращаемая каждым ресурсом в индексе службы, определяется отдельно для этого ресурса. Дополнительные сведения о каждом ресурсе см. в разделах, перечисленных выше.
В будущем по мере развития протокола новые свойства могут быть добавлены в ответы JSON. Для того чтобы клиент был будущим подтверждением, реализация не должна предполагать, что схема ответа является окончательной и не может включать дополнительные данные. Все свойства, которые реализация не понимает, следует игнорировать.
Примечание.
Если источник не реализует SearchAutocompleteService никакого поведения автозавершения, следует отключать корректно. Если ReportAbuseUriTemplate это не реализовано, официальный клиент NuGet возвращается к URL-адресу злоупотреблений в отчете nuget.org (отслеживаемый NuGet/Home#4924). Другие клиенты могут просто не показывать URL-адрес сообщения о злоупотреблении для пользователя.
Незадокументированные ресурсы на nuget.org
Индекс службы версии 3 в nuget.org содержит некоторые ресурсы, которые не описаны выше. Существует несколько причин, по которым не задокументируйте ресурс.
Во-первых, мы не документируем ресурсы, используемые в качестве сведений о реализации nuget.org. Подпадает SearchGalleryQueryService в эту категорию. NuGetGallery использует этот ресурс для делегирования некоторых запросов версии 2 (OData) в индекс поиска вместо использования базы данных. Этот ресурс был введен по соображениям масштабируемости и не предназначен для внешнего использования.
Во-вторых, мы не документируем ресурсы, которые никогда не отправлялись в версию RTM официального клиента.
PackageDisplayMetadataUriTemplate и PackageVersionDisplayMetadataUriTemplate попадает в эту категорию.
В-третьих, мы не документируем ресурсы, которые тесно связаны с протоколом V2, который сам по себе намеренно незадокументирован. Ресурс LegacyGallery попадает в эту категорию. Этот ресурс позволяет индексу службы версии 3 указывать на соответствующий URL-адрес источника версии 2. Этот ресурс поддерживает nuget.exe list.
Если ресурс не указан здесь, настоятельно рекомендуется не учитывать их. Мы можем удалить или изменить поведение этих незадокументированных ресурсов, которые могут нарушить реализацию непредвиденными способами.
Метки времени
Все метки времени, возвращаемые API, являются UTC или указываются в противном случае с использованием представления ISO 8601 .
Методы HTTP
| Команда | Использование |
|---|---|
| GET | Выполняет операцию только для чтения, обычно извлекая данные. |
| HEAD | Извлекает заголовки ответа для соответствующего GET запроса. |
| PUT | Создает ресурс, который не существует или, если он существует, обновляет его. Некоторые ресурсы могут не поддерживать обновление. |
| DELETE | Удаляет или отменяет список ресурсов. |
Коды состояния HTTP
| Код | Описание |
|---|---|
| 200 | Успех и есть текст ответа. |
| 201 | Успешное создание ресурса. |
| 202 | Успешное выполнение запроса было принято, но некоторые работы по-прежнему могут быть неполными и завершены асинхронно. |
| 204 | Успех, но нет текста ответа. |
| 301 | Постоянное перенаправление. |
| 302 | Временное перенаправление. |
| 400 | Параметры в URL-адресе или тексте запроса недопустимы. |
| 401 | Указанные учетные данные недопустимы. |
| 403 | Действие не допускается с указанными учетными данными. |
| 404 | Запрашиваемый ресурс не существует. |
| 409 | Запрос конфликтует с существующим ресурсом. |
| 500 | Служба столкнулась с неожиданной ошибкой. |
| 503 | Служба временно недоступна. |
Любой GET запрос, сделанный в конечную точку API, может возвращать перенаправление HTTP (301 или 302). Клиенты должны корректно обрабатывать такие перенаправления, наблюдая за заголовком Location и выдавая последующий GET. Документация по конкретным конечным точкам не будет явно вызывать, где могут использоваться перенаправления.
В случае кода состояния на уровне 500 клиент может реализовать разумный механизм повтора. Официальный клиент NuGet повторяет три раза при обнаружении любого кода состояния уровня 500 или ошибки TCP/DNS.
Заголовки запросов HTTP
| Имя | Описание |
|---|---|
| X-NuGet-ApiKey | Требуется для отправки и удаления, см PackagePublish . ресурс |
| X-NuGet-Client-Version | Устаревшие и замененные X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Обязательные в некоторых случаях только в nuget.org, см . протоколы nuget.org |
| X-NuGet-Session-Id | Необязательно. Клиенты NuGet версии 4.7+ определяют HTTP-запросы, которые являются частью одного сеанса клиента NuGet. |
Имеет X-NuGet-Session-Id одно значение для всех операций, связанных с одним восстановлением в PackageReference. Для других сценариев, таких как автозавершение и packages.config восстановление, может быть несколько разных идентификаторов сеанса из-за того, как код учитывается.
Проверка подлинности
Проверка подлинности остается до реализации источника пакета, чтобы определить. Для nuget.org только PackagePublish ресурсу требуется проверка подлинности с помощью специального заголовка ключа API. Дополнительные сведения см PackagePublish . в ресурсе .