Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document API Stability changes #6783

Merged
merged 2 commits into from
Apr 27, 2022
Merged

Document API Stability changes #6783

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b108131
Update api version stability
ericholguin Apr 26, 2022
15d7378
make requested changes
ericholguin Apr 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/source/admin/quick_howto/federations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Configure Federations
.. code-block:: shell
:caption: Example cURL Command

curl -i -XPOST "http://localhost:3000/api/2.0/user/login" -H "Content-Type: application/json" -d '{ "u": "federation_user1", "p": "password" }'
curl -i -XPOST "http://localhost:3000/api/4.0/user/login" -H "Content-Type: application/json" -d '{ "u": "federation_user1", "p": "password" }'

.. code-block:: http
:caption: Example API Response
Expand All @@ -74,7 +74,7 @@ Configure Federations
.. code-block:: shell
:caption: Example cURL Command

curl -ki -H "Cookie: mojolicious=eyJleHBpcmVzIjoxNDQ5MTA1MTI2LCJhdXRoX2RhdGEiOiJmZWRlcmF0aW9uX3VzZXIxIn0---06b4f870d809d82a91433e92eae8320875c3e8b0;" -XPUT 'http://localhost:3000/api/2.0/federations' -d '
curl -ki -H "Cookie: mojolicious=eyJleHBpcmVzIjoxNDQ5MTA1MTI2LCJhdXRoX2RhdGEiOiJmZWRlcmF0aW9uX3VzZXIxIn0---06b4f870d809d82a91433e92eae8320875c3e8b0;" -XPUT 'http://localhost:3000/api/4.0/federations' -d '
{"federations": [
{ "deliveryService": "images-c1",
"mappings":
Expand Down
2 changes: 1 addition & 1 deletion docs/source/admin/traffic_router.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ Much of a Traffic Router's configuration can be obtained through the :term:`Para
+-----------------------------------------+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| api.auth.url | CRConfig.json | The URL of the authentication endpoint of the :ref:`to-api` (:ref:`to-api-user-login`). The actual |
| | | :abbr:`FQDN (Fully Qualified Domain Name)` can be subsituted with ``${tmHostname}`` to have Traffic Router automatically fill it in, |
| | | e.g. ``https://${tmHostname}/api/2.0/user/login``. |
| | | e.g. ``https://${tmHostname}/api/4.0/user/login``. |
+-----------------------------------------+------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| consistent.dns.routing | CRConfig.json | Control whether :ref:`DNS-routed <ds-types>` :term:`Delivery Services` use `Consistent Hashing`. May improve performance if set to |
| | | "true"; defaults to "false". |
Expand Down
2 changes: 1 addition & 1 deletion docs/source/admin/traffic_vault.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,4 +361,4 @@ After Riak has been configured to use Riak Search, permissions still need need t
curl --tlsv1.1 --tls-max 1.1 -kvs "https://admin:password@trafficvault.infra.ciab.test:8088/search/query/sslkeys?wt=json&q=cdn:CDN-in-a-Box"

# Verify using the Traffic Ops API
curl -Lvs -H "Cookie: $COOKIE" https://trafficops.infra.ciab.test/api/2.0/cdns/name/mycdn/sslkeys
curl -Lvs -H "Cookie: $COOKIE" https://trafficops.infra.ciab.test/api/4.0/cdns/name/mycdn/sslkeys
34 changes: 11 additions & 23 deletions docs/source/api/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The Traffic Ops API provides programmatic access to read and write Traffic Contr

How to Read this Documentation
==============================
Each endpoint for each version is on its own page, titled with the request path. The request paths shown on each endpoint's page are - unless otherwise noted - only usable by being appended to the request path prefix ``/api/<version>/`` where ``<version>`` is the API version being requested. The API versions officially supported as of the time of this writing are 1.1, 1.2, 1.3, 1.4, 1.5, 2.0. All endpoints are documented as though they were being used in version 1.5 in the version 1 documentation and version 2.0 in the version 2 documentation. If an endpoint or request method of an endpoint is only available after a specific version, that will be noted next to the method or endpoint name. If changes were made to the structure of an endpoint's input or output, the version number and nature of the change will be noted.
Each endpoint for each version is on its own page, titled with the request path. The request paths shown on each endpoint's page are - unless otherwise noted - only usable by being appended to the request path prefix ``/api/<version>/`` where ``<version>`` is the API version being requested. The API versions officially supported as of the time of this writing are 3.0, 4.0. All endpoints are documented as though they were being used in version 3.0 in the version 3 documentation and version 4.0 in the version 4 documentation. If an endpoint or request method of an endpoint is only available after a specific version, that will be noted next to the method or endpoint name. If changes were made to the structure of an endpoint's input or output, the version number and nature of the change will be noted.
ericholguin marked this conversation as resolved.
Show resolved Hide resolved

Every endpoint is documented with a section for each method, containing the subsections "Request Structure" and "Response Structure" which identify all properties and structure of the Request to and Response from the endpoint. Before these subsections, three key pieces of information will be provided:

Expand Down Expand Up @@ -111,11 +111,11 @@ Using API Endpoints

Example Session
---------------
A user makes a request to the ``/api/2.0/asns`` endpoint.
A user makes a request to the ``/api/4.0/asns`` endpoint.

.. code-block:: http

GET /api/2.0/asns HTTP/1.1
GET /api/4.0/asns HTTP/1.1
Accept: application/json
Host: trafficops.infra.ciab.test
User-Agent: example
Expand All @@ -136,11 +136,11 @@ The response JSON indicates an authentication error.
}
]}

To authenticate, the user sends a POST request containing their login information to the ``/api/2.0/user/login`` endpoint.
To authenticate, the user sends a POST request containing their login information to the ``/api/4.0/user/login`` endpoint.

.. code-block:: http

POST /api/2.0/user/login HTTP/1.1
POST /api/4.0/user/login HTTP/1.1
User-Agent: example
Host: trafficops.infra.ciab.test
Accept: application/json
Expand Down Expand Up @@ -169,11 +169,11 @@ Traffic Ops responds with a Mojolicious cookie to be used for future requests, a
}
]}

Using this cookie, the user can now access their original target - the ``/api/2.0/asns`` endpoint...
Using this cookie, the user can now access their original target - the ``/api/4.0/asns`` endpoint...

.. code-block:: http

GET /api/2.0/asns HTTP/1.1
GET /api/4.0/asns HTTP/1.1
Accept: application/json
Cookie: mojolicious=...;
Host: trafficops.infra.ciab.test
Expand Down Expand Up @@ -281,7 +281,7 @@ The most common errors returned by Traffic Ops are:
When a server-side error occurs, the API will return a ``500 INTERNAL SERVER ERROR`` response.

.. code-block:: http
:caption: Example Response to ``GET /api/2.0/servers``. (when a server error such as a postgres failure occured)
:caption: Example Response to ``GET /api/4.0/servers``. (when a server error such as a postgres failure occured)

HTTP/1.1 500 Internal Server Error
Access-Control-Allow-Credentials: true
Expand Down Expand Up @@ -309,23 +309,13 @@ TrafficOps Native Client Libraries
==================================
TrafficOps client libraries are available in Java, Go and Python. You can read (very little) more about them in the client README at :atc-file:`traffic_control/clients`.

API V2 Routes
=============
API routes available in version 2.

.. deprecated:: ATCv6
Traffic Ops API version 2 is deprecated in favor of version 3.

.. toctree::
:maxdepth: 4
:glob:

v2/*

API V3 Routes
=============
API routes available in version 3.

.. deprecated:: ATCv7
Traffic Ops API version 3 is deprecated in favor of version 4.

.. toctree::
:maxdepth: 4
:glob:
Expand All @@ -336,8 +326,6 @@ API V4 Routes
=============
API routes available in version 4.

.. danger:: API version 4 is *unstable*, meaning that breaking changes can occur at any time. Use at your own peril!

.. toctree::
:maxdepth: 4
:glob:
Expand Down
79 changes: 0 additions & 79 deletions docs/source/api/v2/about.rst
View file
Open in desktop

This file was deleted.

106 changes: 0 additions & 106 deletions docs/source/api/v2/api_capabilities.rst
View file
Open in desktop

This file was deleted.

Loading