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 после первого выпуска.
Ресурсы и схема
Индекс службы описывает различные ресурсы. Текущий набор поддерживаемых ресурсов выглядит следующим образом:
| Имя ресурса | Обязательно | Описание |
|---|---|---|
| каталога | Нет | Полная запись всех событий пакета. |
| PackageBaseAddress | да | Получение содержимого пакета (NUPKG). |
| PackageDetailsUriTemplate | Нет | Создайте URL-адрес для доступа к веб-странице сведений о пакете. |
| PackagePublish | да | Отправка и удаление (или отмена списка) пакетов. |
| ReadmeUriTemplate | Нет | Создайте URL-адрес для доступа к README пакета. |
| RegistrationsBaseUrl | да | Получение метаданных пакета. |
| ReportAbuseUriTemplate | Нет | Создайте URL-адрес для доступа к веб-странице злоупотреблений отчетом. |
| РепозиторийSignatures | Нет | Получение сертификатов, используемых для подписи репозитория. |
| SearchAutocompleteService | Нет | Обнаружение идентификаторов пакетов и версий путем подстроки. |
| SearchQueryService | да | Фильтрация и поиск пакетов по ключевому слову. |
| SymbolPackagePublish | Нет | Отправка пакетов символов. |
| VulnerabilityInfo | Нет | Пакеты с известными уязвимостями. |
Как правило, все не двоичные данные, возвращаемые ресурсом API, сериализуются с помощью JSON. Схема ответа, возвращаемая каждым ресурсом в индексе службы, определяется отдельно для этого ресурса. Дополнительные сведения о каждом ресурсе см. в разделах, перечисленных выше.
В будущем по мере развития протокола новые свойства могут быть добавлены в ответы JSON. Для того чтобы клиент был будущим подтверждением, реализация не должна предполагать, что схема ответа является окончательной и не может включать дополнительные данные. Все свойства, которые реализация не понимает, следует игнорировать.
Заметка
Если источник не реализует SearchAutocompleteService любое поведение автозаполнения должно быть отключено корректно. Если ReportAbuseUriTemplate не реализовано, официальный клиент NuGet возвращается к URL-адресу о злоупотреблении в отчете nuget.org (отслеживаемый NuGet/Home#4924). Другие клиенты могут просто не показывать URL-адрес сообщения о злоупотреблении для пользователя.
Незадокументированные ресурсы на nuget.org
Индекс службы версии 3 в nuget.org содержит некоторые ресурсы, которые не описаны выше. Существует несколько причин, по которым не задокументируйте ресурс.
Во-первых, мы не документируем ресурсы, используемые в качестве сведений о реализации nuget.org. SearchGalleryQueryService попадает в эту категорию.
NuGetGallery использует этот ресурс для делегирования некоторых запросов V2 (OData) в индекс поиска вместо использования базы данных. Этот ресурс был введен по соображениям масштабируемости и не предназначен для внешнего использования.
Во-вторых, мы не документируем ресурсы, которые никогда не отправлялись в версию RTM официального клиента.
PackageDisplayMetadataUriTemplate и PackageVersionDisplayMetadataUriTemplate относятся к этой категории.
В-третьих, мы не документируем ресурсы, которые тесно связаны с протоколом V2, который сам по себе намеренно незадокументирован. Ресурс LegacyGallery попадает в эту категорию. Этот ресурс позволяет индексу службы версии 3 указывать на соответствующий URL-адрес источника версии 2. Этот ресурс поддерживает nuget.exe list.
Если ресурс не указан здесь, мы настоятельно рекомендуем не принимать зависимостей. Мы можем удалить или изменить поведение этих незадокументированных ресурсов, которые могут нарушить реализацию непредвиденными способами.
Временные метки
Все метки времени, возвращаемые API, указаны в формате UTC или указаны в противном случае с помощью представления ISO 8601.
Методы HTTP
| Глагол | Использование |
|---|---|
| ПОЛУЧИТЬ | Выполняет операцию только для чтения, обычно извлекая данные. |
| ГОЛОВА | Извлекает заголовки ответа для соответствующего запроса GET. |
| КЛАСТЬ | Создает ресурс, который не существует или, если он существует, обновляет его. Некоторые ресурсы могут не поддерживать обновление. |
| УДАЛИТЬ | Удаляет или отменяет список ресурсов. |
Коды состояния 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 ресурса.