diff --git a/docs/topics/api/abuse.rst b/docs/topics/api/abuse.rst index e1eb017b18..6b56c7d07e 100644 --- a/docs/topics/api/abuse.rst +++ b/docs/topics/api/abuse.rst @@ -2,6 +2,12 @@ Abuse Reports ============= +.. note:: + + These APIs are experimental and are currently being worked on. Endpoints + may change without warning. Consider the :ref:`v3 API` + if you need stability. + The following API endpoint covers abuse reporting --------------------------------- @@ -15,7 +21,7 @@ either listed on https://addons.mozilla.org or not. Authentication is not required, but is recommended so reports can be responded to if nessecary. -.. http:post:: /api/v3/abuse/report/addon/ +.. http:post:: /api/v4/abuse/report/addon/ .. _addonabusereport-create-request: @@ -43,7 +49,7 @@ The following API endpoint allows an abuse report to be submitted for a user acc on https://addons.mozilla.org. Authentication is not required, but is recommended so reports can be responded to if nessecary. -.. http:post:: /api/v3/abuse/report/user/ +.. http:post:: /api/v4/abuse/report/user/ .. _userabusereport-create-request: diff --git a/docs/topics/api/accounts.rst b/docs/topics/api/accounts.rst index 333ac72f55..1e084dd83d 100644 --- a/docs/topics/api/accounts.rst +++ b/docs/topics/api/accounts.rst @@ -2,8 +2,14 @@ Accounts ======== -The following API endpoints cover a users account. +.. note:: + These APIs are experimental and are currently being worked on. Endpoints + may change without warning. Consider the :ref:`v3 API` + if you need stability. The only authentication method available at + the moment is :ref:`the internal one`. + +The following API endpoints cover a users account. ------- Account @@ -20,7 +26,7 @@ Most of the information is optional and provided by the user so may be missing o A developer is defined as a user who is listed as a developer or owner of one or more approved add-ons. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/ +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/ .. _account-object: @@ -47,7 +53,7 @@ If you authenticate and access your own account by specifing your own ``user_id` You can always access your account, regardless of whether you are a developer or not. If you have `Users:Edit` permission you will see these extra fields for all user accounts. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/ +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/ .. _account-object-self: @@ -104,7 +110,7 @@ Profile This endpoint is a shortcut to your own account. It returns an :ref:`account object ` -.. http:get:: /api/v3/accounts/profile/ +.. http:get:: /api/v4/accounts/profile/ ---- @@ -121,7 +127,7 @@ This endpoint allows some of the details for an account to be updated. Any fiel in the :ref:`account ` (or :ref:`self `) but not listed below are not editable and will be ignored in the patch request. -.. http:patch:: /api/v3/accounts/account/(int:user_id|string:username)/ +.. http:patch:: /api/v4/accounts/account/(int:user_id|string:username)/ .. _account-edit-request: @@ -141,13 +147,13 @@ To upload a picture for the profile the request must be sent as content-type `mu Images must be either PNG or JPG; the maximum file size is 4MB. Other :ref:`editable values ` can be set at the same time. -.. http:patch:: /api/v3/accounts/account/(int:user_id|string:username)/ +.. http:patch:: /api/v4/accounts/account/(int:user_id|string:username)/ **Request:** .. sourcecode:: bash - curl "https://addons.mozilla.org/api/v3/accounts/account/12345/" + curl "https://addons.mozilla.org/api/v4/accounts/account/12345/" -g -XPATCH --form "picture_upload=@photo.png" -H "Authorization: Bearer " @@ -162,7 +168,7 @@ Deleting the picture To delete the account profile picture call the special endpoint. -.. http:delete:: /api/v3/accounts/account/(int:user_id|string:username)/picture +.. http:delete:: /api/v4/accounts/account/(int:user_id|string:username)/picture ------ @@ -183,7 +189,7 @@ This endpoint allows the account to be deleted. The reviews and ratings created by the user will not be deleted; but all the user's details are cleared. -.. http:delete:: /api/v3/accounts/account/(int:user_id|string:username)/ +.. http:delete:: /api/v4/accounts/account/(int:user_id|string:username)/ ------------------ @@ -199,7 +205,7 @@ Notifications List This endpoint allows you to list the account notifications set for the specified user. The result is an unpaginated list of the fields below. There are currently 11 notification types. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/notifications/ +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/notifications/ :>json string name: The notification short name. :>json boolean enabled: If the notification is enabled (defaults to True). @@ -219,7 +225,7 @@ Notifications Update This endpoint allows account notifications to be set or updated. The request should be a dict of `name`:True|False pairs. Any number of notifications can be changed; only non-mandatory notifications can be changed - attempting to set a mandatory notification will return an error. -.. http:post:: /api/v3/accounts/account/(int:user_id|string:username)/notifications/ +.. http:post:: /api/v4/accounts/account/(int:user_id|string:username)/notifications/ .. _notification-update-request: @@ -243,7 +249,7 @@ This allows you to generate a new user account and sign in as that user. * This endpoint is not available in all :ref:`API environments `. -.. http:post:: /api/v3/accounts/super-create/ +.. http:post:: /api/v4/accounts/super-create/ **Request:** @@ -266,7 +272,7 @@ This allows you to generate a new user account and sign in as that user. .. sourcecode:: bash - curl "https://addons.mozilla.org/api/v3/accounts/super-create/" \ + curl "https://addons.mozilla.org/api/v4/accounts/super-create/" \ -X POST -H "Authorization: JWT " **Response:** @@ -310,13 +316,13 @@ Log out of the current session. This is for use with the :ref:`internal authentication ` that authenticates browser sessions. -.. http:delete:: /api/v3/accounts/session/ +.. http:delete:: /api/v4/accounts/session/ **Request:** .. sourcecode:: bash - curl "https://addons.mozilla.org/api/v3/accounts/session/" + curl "https://addons.mozilla.org/api/v4/accounts/session/" -H "Authorization: Bearer " -X DELETE **Response:** diff --git a/docs/topics/api/activity.rst b/docs/topics/api/activity.rst index 5eae56b375..beece0eb06 100644 --- a/docs/topics/api/activity.rst +++ b/docs/topics/api/activity.rst @@ -5,7 +5,8 @@ Activity .. note:: These APIs are experimental and are currently being worked on. Endpoints - may change without warning. The only authentication method available at + may change without warning. Consider the :ref:`v3 API` + if you need stability. The only authentication method available at the moment is :ref:`the internal one`. @@ -17,7 +18,7 @@ Review Notes List This endpoint allows you to list the approval/rejection review history for a version of an add-on. -.. http:get:: /api/v3/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id)/reviewnotes/ +.. http:get:: /api/v4/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id)/reviewnotes/ .. note:: All add-ons require authentication and either @@ -38,7 +39,7 @@ Review Notes Detail This endpoint allows you to fetch a single review note for a specific version of an add-on. -.. http:get:: /api/v3/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id)/reviewnotes/(int:id)/ +.. http:get:: /api/v4/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id)/reviewnotes/(int:id)/ .. _review-notes-version-detail-object: @@ -80,7 +81,7 @@ This endpoint allows a mail server or similar to submit a json object containing The only type of email currently supported is a reply to an activity email (e.g an add-on review, or a reply to an add-on review). Any other content or invalid emails will be discarded. -.. http:post:: /api/v3/activity/mail +.. http:post:: /api/v4/activity/mail .. note:: This API endpoint uses a custom authentication method. @@ -91,4 +92,3 @@ Any other content or invalid emails will be discarded. :` + if you need stability. The only authentication method available at the moment is :ref:`the internal one`. -------- @@ -20,7 +21,7 @@ are not accepted. The query parameter ``page_size`` is allowed but only serves to customize the number of results returned, clients can not request a specific page. -.. http:get:: /api/v3/addons/featured/ +.. http:get:: /api/v4/addons/featured/ :query string app: **Required**. Filter by :ref:`add-on application ` availability. :query string category: Filter by :ref:`category slug `. ``app`` and ``type`` parameters need to be set, otherwise this parameter is ignored. @@ -37,7 +38,7 @@ Search This endpoint allows you to search through public add-ons. -.. http:get:: /api/v3/addons/search/ +.. http:get:: /api/v4/addons/search/ :query string q: The search query. The maximum length allowed is 100 characters. :query string app: Filter by :ref:`add-on application ` availability. @@ -103,7 +104,7 @@ for autocomplete though, there are a couple key differences: results will be returned at all times. - Only a subset of fields are returned. -.. http:get:: /api/v3/addons/autocomplete/ +.. http:get:: /api/v4/addons/autocomplete/ :query string q: The search query. :query string app: Filter by :ref:`add-on application ` availability. @@ -139,7 +140,7 @@ This endpoint allows you to fetch a specific add-on by id, slug or guid. * ``is_disabled_by_developer``: boolean set to ``true`` when the add-on has been voluntarily disabled by its developer. * ``is_disabled_by_mozilla``: boolean set to ``true`` when the add-on has been disabled by Mozilla. -.. http:get:: /api/v3/addons/addon/(int:id|string:slug|string:guid)/ +.. http:get:: /api/v4/addons/addon/(int:id|string:slug|string:guid)/ .. _addon-detail-object: @@ -290,7 +291,7 @@ Versions List This endpoint allows you to list all versions belonging to a specific add-on. -.. http:get:: /api/v3/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/ +.. http:get:: /api/v4/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/ .. note:: Non-public add-ons and add-ons with only unlisted versions require both: @@ -336,7 +337,7 @@ Version Detail This endpoint allows you to fetch a single version belonging to a specific add-on. -.. http:get:: /api/v3/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id)/ +.. http:get:: /api/v4/addons/addon/(int:addon_id|string:addon_slug|string:addon_guid)/versions/(int:id)/ .. _version-detail-object: @@ -397,7 +398,7 @@ Add-on Feature Compatibility This endpoint allows you to fetch feature compatibility information for a a specific add-on by id, slug or guid. -.. http:get:: /api/v3/addons/addon/(int:id|string:slug|string:guid)/feature_compatibility/ +.. http:get:: /api/v4/addons/addon/(int:id|string:slug|string:guid)/feature_compatibility/ .. note:: Non-public add-ons and add-ons with only unlisted versions require both: @@ -424,7 +425,7 @@ Add-on EULA and Privacy Policy This endpoint allows you to fetch an add-on EULA and privacy policy. -.. http:get:: /api/v3/addons/addon/(int:id|string:slug|string:guid)/eula_policy/ +.. http:get:: /api/v4/addons/addon/(int:id|string:slug|string:guid)/eula_policy/ .. note:: Non-public add-ons and add-ons with only unlisted versions require both: @@ -445,7 +446,7 @@ Language Tools This endpoint allows you to list all public language tools add-ons available on AMO. -.. http:get:: /api/v3/addons/language-tools/ +.. http:get:: /api/v4/addons/language-tools/ .. note:: Because this endpoint is intended to be used to feed a page that @@ -485,7 +486,7 @@ Replacement Add-ons This endpoint returns a list of suggested replacements for legacy add-ons that are unsupported in Firefox 57. Added to support the TAAR recommendation service. -.. http:get:: /api/v3/addons/replacement-addon/ +.. http:get:: /api/v4/addons/replacement-addon/ :query int page: 1-based page number. Defaults to 1. :query int page_size: Maximum number of results to return for the requested page. Defaults to 25. @@ -506,7 +507,7 @@ Compat Override This endpoint allows compatibility overrides specified by AMO admins to be searched. Compatibilty overrides are used within Firefox i(and other toolkit applications e.g. Thunderbird) to change compatibility of installed add-ons where they have stopped working correctly in new release of Firefox, etc. -.. http:get:: /api/v3/addons/compat-override/ +.. http:get:: /api/v4/addons/compat-override/ :query string guid: Filter by exact add-on guid. Multiple guids can be specified, separated by comma(s), in which case any add-ons matching any of the guids will be returned. As guids are unique there should be at most one add-on result per guid specified. :query int page: 1-based page number. Defaults to 1. @@ -538,7 +539,7 @@ Recommendations This endpoint provides recommendations of other addons to install, fetched from the `recommendation service `_. Four recommendations are fetched, but only valid, publicly available addons are shown (so max 4 will be returned, and possibly less). -.. http:get:: /api/v3/addons/recommendations/ +.. http:get:: /api/v4/addons/recommendations/ :query string guid: Fetch recommendations for this add-on guid. :query string lang: Activate translations in the specific language for that query. (See :ref:`translated fields `) diff --git a/docs/topics/api/auth.rst b/docs/topics/api/auth.rst index b7495e5425..8d159663f0 100644 --- a/docs/topics/api/auth.rst +++ b/docs/topics/api/auth.rst @@ -123,7 +123,7 @@ Using the :ref:`profile ` as an example endpoint, here's what a JWT authenticated HTTP request would look like in `curl `_:: - curl "https://addons.mozilla.org/api/v3/accounts/profile/" \ + curl "https://addons.mozilla.org/api/v4/accounts/profile/" \ -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ5b3VyLWFwaS1rZXkiLCJqdGkiOiIwLjQ3MzYyOTQ0NjIzNDU1NDA1IiwiaWF0IjoxNDQ3MjczMDk2LCJleHAiOjE0NDcyNzMxNTZ9.fQGPSV85QPhbNmuu86CIgZiluKBvZKd-NmzM6vo11DM" diff --git a/docs/topics/api/auth_internal.rst b/docs/topics/api/auth_internal.rst index c7a7eec74f..19a3819828 100644 --- a/docs/topics/api/auth_internal.rst +++ b/docs/topics/api/auth_internal.rst @@ -22,7 +22,7 @@ Fetching the token A fresh token, valid for 30 days, is automatically generated and added to the responses of the following endpoint: - * ``/api/v3/accounts/authenticate/`` + * ``/api/v4/accounts/authenticate/`` The token is available in two forms: diff --git a/docs/topics/api/categories.rst b/docs/topics/api/categories.rst index 5ee969cfb7..06f9c23f3b 100644 --- a/docs/topics/api/categories.rst +++ b/docs/topics/api/categories.rst @@ -5,7 +5,8 @@ Categories .. note:: These APIs are experimental and are currently being worked on. Endpoints - may change without warning. + may change without warning. Consider the :ref:`v3 API` + if you need stability. ------------- Category List @@ -19,7 +20,7 @@ can therefore be re-used for different categories. This endpoint is not paginated. -.. http:get:: /api/v3/addons/categories/ +.. http:get:: /api/v4/addons/categories/ :>json int id: The category id. :>json string name: The category name. Returns the already translated string. diff --git a/docs/topics/api/collections.rst b/docs/topics/api/collections.rst index b3ff82f685..d108015884 100644 --- a/docs/topics/api/collections.rst +++ b/docs/topics/api/collections.rst @@ -2,6 +2,13 @@ Collections =========== +.. note:: + + These APIs are experimental and are currently being worked on. Endpoints + may change without warning. Consider the :ref:`v3 API` + if you need stability. The only authentication method available at + the moment is :ref:`the internal one`. + The following API endpoints cover user created collections. @@ -19,7 +26,7 @@ This endpoint allows you to list all collections authored by the specified user. The results are sorted by the most recently updated collection first. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/collections/ +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/collections/ :>json int count: The number of results for this query. :>json string next: The URL of the next page of results. @@ -39,7 +46,7 @@ a non-``public`` collection only if it was authored by you, the authenticated us If your account has the `Collections:Edit` permission then you can access any collection. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/ +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/ .. _collection-detail-object: @@ -65,7 +72,7 @@ Filtering is as per :ref:`collection addon list endpoint`. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/?with_addons +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/?with_addons .. _collection-detail-object-with-addons: @@ -89,7 +96,7 @@ Create This endpoint allows a collection to be created under your account. Any fields in the :ref:`collection ` but not listed below are not settable and will be ignored in the request. -.. http:post:: /api/v3/accounts/account/(int:user_id|string:username)/collections/ +.. http:post:: /api/v4/accounts/account/(int:user_id|string:username)/collections/ .. _collection-create-request: @@ -113,7 +120,7 @@ Edit This endpoint allows some of the details for a collection to be updated. Any fields in the :ref:`collection ` but not listed below are not editable and will be ignored in the patch request. -.. http:patch:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/ +.. http:patch:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/ .. _collection-edit-request: @@ -136,7 +143,7 @@ Delete This endpoint allows the collection to be deleted. -.. http:delete:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/ +.. http:delete:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/ @@ -148,7 +155,7 @@ Collection Add-ons List This endpoint lists the add-ons in a collection, together with collector's notes. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/ +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/ :query string filter: The :ref:`filter ` to apply. :query string sort: The sort parameter. The available parameters are documented in the :ref:`table below `. @@ -199,7 +206,7 @@ Collection Add-ons Detail This endpoint gets details of a single add-on in a collection, together with collector's notes. -.. http:get:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/(int:addon_id|string:slug)/ +.. http:get:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/(int:addon_id|string:slug)/ .. _collection-addon-detail-object: @@ -220,7 +227,7 @@ Collection Add-ons Create This endpoint allows a single add-on to be added to a collection, optionally with collector's notes. -.. http:post:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/ +.. http:post:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/ :`). @@ -238,7 +245,7 @@ Collection Add-ons Edit This endpoint allows the collector's notes for single add-on to be updated. -.. http:patch:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/(int:addon_id|string:slug)/ +.. http:patch:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/(int:addon_id|string:slug)/ :`). @@ -255,4 +262,4 @@ Collection Add-ons Delete This endpoint allows a single add-on to be removed from a collection. -.. http:delete:: /api/v3/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/(int:addon_id|string:slug)/ +.. http:delete:: /api/v4/accounts/account/(int:user_id|string:username)/collections/(string:collection_slug)/addons/(int:addon_id|string:slug)/ diff --git a/docs/topics/api/discovery.rst b/docs/topics/api/discovery.rst index 02d86cac99..e557663961 100644 --- a/docs/topics/api/discovery.rst +++ b/docs/topics/api/discovery.rst @@ -3,8 +3,10 @@ Discovery ========= .. note:: + These APIs are experimental and are currently being worked on. Endpoints - may change without warning. + may change without warning. Consider the :ref:`v3 API` + if you need stability. ----------------- Discovery Content @@ -15,7 +17,7 @@ Discovery Content This endpoint allows you to fetch content for the new Discovery Pane in Firefox (about:addons). - .. http:get:: /api/v3/discovery/ + .. http:get:: /api/v4/discovery/ :query string lang: Activate translations in the specific language for that query. (See :ref:`translated fields `) :query string edition: Return content for a specific edition of Firefox. Currently only ``china`` is supported. @@ -48,7 +50,7 @@ be replaced. The API will still return a total of 7 items. is ignored and standard discovery response returned. - .. http:get:: /api/v3/discovery/?telemetry-client-id=12345678-90ab-cdef-1234-567890abcdef + .. http:get:: /api/v4/discovery/?telemetry-client-id=12345678-90ab-cdef-1234-567890abcdef :query string telemetry-client-id: The telemetry client ID to be passed to the TAAR service. :query string lang: In addition to activating translations (see :ref:`Discovery Content `), this will be passed as `locale` to TAAR. diff --git a/docs/topics/api/github.rst b/docs/topics/api/github.rst index 2e439f6009..863fdf5d6f 100644 --- a/docs/topics/api/github.rst +++ b/docs/topics/api/github.rst @@ -4,14 +4,16 @@ GitHub Webhooks .. note:: - This is an Experimental API and can change at any time. + These APIs are experimental and are currently being worked on. Endpoints + may change without warning. Consider the :ref:`v3 API` + if you need stability. This API provides an endpoint that works with GitHub to provide add-on validation as a GitHub webhook. This end point is designed to be called specifically from GitHub and will only send API responses back to `api.github.com`. To set this up on a GitHub repository you will need to: * Go to `Settings > Webhooks & Services` -* Add a new Webhook with Payload URL of `https://addons.mozilla.org/api/v3/github/validate/` +* Add a new Webhook with Payload URL of `https://addons.mozilla.org/api/v4/github/validate/` * Click `Send me everything` * Click `Update webhook` @@ -26,11 +28,11 @@ If this service proves useful and this service transitions from its Experimental The validator will run when you create or alter a pull request. -.. http:post:: /api/v3/github/validate/ +.. http:post:: /api/v4/github/validate/ **Request:** - A `GitHub API webhook `_ body. Currently only `pull_request` events are processed, all others are ignored. + A `GitHub API webhook `_ body. Currently only `pull_request` events are processed, all others are ignored. **Response:** diff --git a/docs/topics/api/index.rst b/docs/topics/api/index.rst index b85222a3f9..1b383fc154 100644 --- a/docs/topics/api/index.rst +++ b/docs/topics/api/index.rst @@ -3,16 +3,16 @@ External API ============ This shows you how to use the `addons.mozilla.org `_ -API at ``/api/v3/`` which is hosted at the following URLs: +API at ``/api/v4/`` which is hosted at the following URLs: .. _api-environments: =========== ========================================= Environment URL =========== ========================================= -Production ``https://addons.mozilla.org/api/v3/`` -Staging ``https://addons.allizom.org/api/v3/`` -Development ``https://addons-dev.allizom.org/api/v3/`` +Production ``https://addons.mozilla.org/api/v4/`` +Staging ``https://addons.allizom.org/api/v4/`` +Development ``https://addons-dev.allizom.org/api/v4/`` =========== ========================================= Production diff --git a/docs/topics/api/overview.rst b/docs/topics/api/overview.rst index f4b3995f61..78d163984d 100644 --- a/docs/topics/api/overview.rst +++ b/docs/topics/api/overview.rst @@ -4,6 +4,12 @@ Overview ======== +.. note:: + + These APIs are experimental and are currently being worked on. Endpoints + may change without warning. Consider the :ref:`v3 API` + if you need stability. + This describes the details of the requests and responses you can expect from the `addons.mozilla.org `_ API. @@ -25,7 +31,7 @@ Status Codes There are some common API responses that you can expect to receive at times. -.. http:get:: /api/v3/... +.. http:get:: /api/v4/... :statuscode 200: Success. :statuscode 201: Creation successful. @@ -162,3 +168,19 @@ specified. .. _`Cross-Origin Resource Sharing`: https://developer.mozilla.org/en-US/docs/HTTP/Access_control_CORS + +.. _api-stable-v3: + +------------- +Stable v3 API +------------- + +All documentation here refers to the in-development `v4` APIs, which are +experimental. Any consumer of the APIs that require stablity may consider using +the `v3` API instead, which is frozen. No new API endpoints will be added to +`v3` and we aim to make no breaking changes. (That's the aim - we can't +guarantee 100% stability). The `v3` API will be maintained for as long as Firefox +ESR60 is supported by Mozilla, i.e. at least June 30th 2019. +The downside of using the `v3` API is, of course, no new cool features! + +The documentation for `v3` can be accessed at: http://addons-server.readthedocs.io/en/2018.05.17/topics/api/ diff --git a/docs/topics/api/reviewers.rst b/docs/topics/api/reviewers.rst index 48bd6c2e7b..a60ff58aab 100644 --- a/docs/topics/api/reviewers.rst +++ b/docs/topics/api/reviewers.rst @@ -7,7 +7,8 @@ Reviewers .. note:: These APIs are experimental and are currently being worked on. Endpoints - may change without warning. The only authentication method available at + may change without warning. Consider the :ref:`v3 API` + if you need stability. The only authentication method available at the moment is :ref:`the internal one`. --------- @@ -21,7 +22,7 @@ sent when a new listed version is submitted on a particular add-on. Requires authentication and the current user to have any reviewer-related permission. -.. http:post::/api/v3/reviewers/addon/(int:addon_id)/subscribe/ +.. http:post::/api/v4/reviewers/addon/(int:addon_id)/subscribe/ ----------- Unsubscribe @@ -34,7 +35,7 @@ sent when a new listed version is submitted on a particular add-on. Requires authentication and the current user to have any reviewer-related permission. -.. http:post::/api/v3/reviewers/addon/(int:addon_id)/unsubscribe/ +.. http:post::/api/v4/reviewers/addon/(int:addon_id)/unsubscribe/ ------- Disable @@ -46,7 +47,7 @@ This endpoint allows you to disable the public listing for an add-on. Requires authentication and the current user to have ``Reviews:Admin`` permission. -.. http:post::/api/v3/reviewers/addon/(int:addon_id)/disable/ +.. http:post::/api/v4/reviewers/addon/(int:addon_id)/disable/ ------ Enable @@ -61,7 +62,7 @@ of its versions. Requires authentication and the current user to have ``Reviews:Admin`` permission. -.. http:post::/api/v3/reviewers/addon/(int:addon_id)/enable/ +.. http:post::/api/v4/reviewers/addon/(int:addon_id)/enable/ ----- @@ -70,11 +71,12 @@ Flags This endpoint allows you to manipulate various reviewer-specific flags on an add-on. + .. note:: Requires authentication and the current user to have ``Reviews:Admin`` - permission. + permission. -.. http:patch::/api/v3/reviewers/addon/(int:addon_id)/flags/ +.. http:patch::/api/v4/reviewers/addon/(int:addon_id)/flags/ :>json boolean auto_approval_disabled: Boolean indicating whether auto approval are disabled on an add-on or not. When it's ``true``, new versions for this add-on will make it appear in the regular reviewer queues instead of being auto-approved. :>json string|null pending_info_request: Deadline date for the pending info request as a string, or ``null``. diff --git a/docs/topics/api/reviews.rst b/docs/topics/api/reviews.rst index ddc149b081..bf96b58dda 100644 --- a/docs/topics/api/reviews.rst +++ b/docs/topics/api/reviews.rst @@ -5,7 +5,8 @@ Reviews .. note:: These APIs are experimental and are currently being worked on. Endpoints - may change without warning. The only authentication method available at + may change without warning. Consider the :ref:`v3 API` + if you need stability. The only authentication method available at the moment is :ref:`the internal one`. ------------ @@ -23,7 +24,7 @@ When ``addon``, ``user`` and ``version`` are passed on the same request, one review per version of a given add-on. This can be useful to find out if a user has already posted a review for the current version of an add-on. -.. http:get:: /api/v3/reviews/review/ +.. http:get:: /api/v4/reviews/review/ :query string addon: The :ref:`add-on ` id, slug, or guid to fetch reviews from. When passed, the reviews shown will always be the latest posted by each user on this particular add-on (which means there should only be one review per user in the results), unless the ``version`` parameter is also passed. :query string filter: The :ref:`filter(s) ` to apply. @@ -63,7 +64,7 @@ Detail This endpoint allows you to fetch a review by its id. -.. http:get:: /api/v3/reviews/review/(int:id)/ +.. http:get:: /api/v4/reviews/review/(int:id)/ .. _review-detail-object: @@ -96,7 +97,7 @@ If successful a :ref:`review object ` is returned. Requires authentication. -.. http:post:: /api/v3/reviews/review/ +.. http:post:: /api/v4/reviews/review/ :` is returned. Only body, title and rating are allowed for modification. -.. http:patch:: /api/v3/reviews/review/(int:id)/ +.. http:patch:: /api/v4/reviews/review/(int:id)/ :` is returned. Requires authentication and either Addons:Edit permission or a user account listed as a developer of the add-on. -.. http:post:: /api/v3/reviews/review/(int:id)/reply/ +.. http:post:: /api/v4/reviews/review/(int:id)/reply/ :` describing the reason behind the flagging. :`. +.. note:: + + These APIs are experimental and are currently being worked on. Endpoints + may change without warning. Consider the :ref:`v3 API` + if you need stability. The following API endpoints help you get your add-on signed by Mozilla so it can be installed into Firefox without error. See @@ -40,13 +44,13 @@ validation or review fails. If the upload succeeded then it will be submitted for validation and you will be able to check its status. -.. http:put:: /api/v3/addons/[string:addon-id]/versions/[string:version]/ +.. http:put:: /api/v4/addons/[string:addon-id]/versions/[string:version]/ **Request:** .. sourcecode:: bash - curl "https://addons.mozilla.org/api/v3/addons/@my-addon/versions/1.0/" + curl "https://addons.mozilla.org/api/v4/addons/@my-addon/versions/1.0/" -g -XPUT --form "upload=@build/my-addon.xpi" -H "Authorization: JWT " @@ -87,13 +91,13 @@ Uploading without an ID endpoint to :ref:`upload a version `. -.. http:post:: /api/v3/addons/ +.. http:post:: /api/v4/addons/ **Request:** .. sourcecode:: bash - curl "https://addons.mozilla.org/api/v3/addons/" + curl "https://addons.mozilla.org/api/v4/addons/" -g -XPOST -F "upload=@build/my-addon.xpi" -F "version=1.0" -H "Authorization: JWT " @@ -143,13 +147,13 @@ automatically or after a manual review. Once review is complete then the ``reviewed`` property will be set and you can check the results with the ``passed_review`` property. -.. http:get:: /api/v3/addons/[string:addon-id]/versions/[string:version]/(uploads/[string:upload-pk]/) +.. http:get:: /api/v4/addons/[string:addon-id]/versions/[string:version]/(uploads/[string:upload-pk]/) **Request:** .. sourcecode:: bash - curl "https://addons.mozilla.org/api/v3/addons/@my-addon/versions/1.0/" + curl "https://addons.mozilla.org/api/v4/addons/@my-addon/versions/1.0/" -g -H "Authorization: JWT " :param addon-id: the id for the add-on. @@ -166,7 +170,7 @@ automatically or after a manual review. Once review is complete then the "automated_signing": true, "files": [ { - "download_url": "https://addons.mozilla.org/api/v3/downloads/file/100/example-id.0-fx+an.xpi?src=api", + "download_url": "https://addons.mozilla.org/api/v4/downloads/file/100/example-id.0-fx+an.xpi?src=api", "hash": "sha256:1bb945266bf370170a656350d9b640cbcaf70e671cf753c410e604219cdd9267", "signed": true } @@ -175,7 +179,7 @@ automatically or after a manual review. Once review is complete then the "pk": "f68abbb3b1624c098fe979a409fe3ce9", "processed": true, "reviewed": true, - "url": "https://addons.mozilla.org/api/v3/addons/@example-id.0/uploads/f68abbb3b1624c098fe979a409fe3ce9/", + "url": "https://addons.mozilla.org/api/v4/addons/@example-id.0/uploads/f68abbb3b1624c098fe979a409fe3ce9/", "valid": true, "validation_results": {}, "validation_url": "https://addons.mozilla.org/en-US/developers/upload/f68abbb3b1624c098fe979a409fe3ce9", @@ -220,13 +224,13 @@ When checking on your :ref:`request to sign a version `, a successful response will give you an API URL to download the signed files. This endpoint returns the actual file data for download. -.. http:get:: /api/v3/file/[int:file_id]/[string:base_filename] +.. http:get:: /api/v4/file/[int:file_id]/[string:base_filename] **Request:** .. sourcecode:: bash - curl "https://addons.mozilla.org/api/v3/file/123/some-addon.xpi?src=api" + curl "https://addons.mozilla.org/api/v4/file/123/some-addon.xpi?src=api" -g -H "Authorization: JWT " :param file_id: the primary key of the add-on file. diff --git a/docs/topics/development/debugging.rst b/docs/topics/development/debugging.rst index 77f287f007..8a1356b0fb 100644 --- a/docs/topics/development/debugging.rst +++ b/docs/topics/development/debugging.rst @@ -33,7 +33,7 @@ All being well it should look like this:: 11:02:08 py.warnings:WARNING /opt/rh/python27/root/usr/lib/python2.7/site-packages/jwt/api_jws.py:118: DeprecationWarning: The verify parameter is deprecated. Please use options instead. 'Please use options instead.', DeprecationWarning) :/opt/rh/python27/root/usr/lib/python2.7/site-packages/jwt/api_jws.py:118 - [21/Oct/2015 11:02:08] "PUT /en-US/firefox/api/v3/addons/%40unlisted/versions/0.0.5/ HTTP/1.1" 400 36 + [21/Oct/2015 11:02:08] "PUT /en-US/firefox/api/v4/addons/%40unlisted/versions/0.0.5/ HTTP/1.1" 400 36 Validating models... 0 errors found