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 . в ресурсе .