http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/2ca12610/docs/master/_sources/api/v11/user.rst.txt ---------------------------------------------------------------------- diff --git a/docs/master/_sources/api/v11/user.rst.txt b/docs/master/_sources/api/v11/user.rst.txt new file mode 100644 index 0000000..2ef5012 --- /dev/null +++ b/docs/master/_sources/api/v11/user.rst.txt @@ -0,0 +1,778 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +.. _to-api-v11-users: + +Users +===== + +.. _to-api-v11-users-route: + +/api/1.1/users +++++++++++++++ + +**GET /api/1.1/users** + + Retrieves all users. + + Authentication Required: Yes + + Role(s) Required: None + + **Response Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``addressLine1`` | string | | + +----------------------+--------+------------------------------------------------+ + |``addressLine2`` | string | | + +----------------------+--------+------------------------------------------------+ + |``city`` | string | | + +----------------------+--------+------------------------------------------------+ + |``company`` | string | | + +----------------------+--------+------------------------------------------------+ + |``country`` | string | | + +----------------------+--------+------------------------------------------------+ + |``email`` | string | | + +----------------------+--------+------------------------------------------------+ + |``fullName`` | string | | + +----------------------+--------+------------------------------------------------+ + |``gid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``id`` | hash | | + +----------------------+--------+------------------------------------------------+ + |``lastUpdated`` | string | | + +----------------------+--------+------------------------------------------------+ + |``newUser`` | string | | + +----------------------+--------+------------------------------------------------+ + |``phoneNumber`` | string | | + +----------------------+--------+------------------------------------------------+ + |``postalCode`` | string | | + +----------------------+--------+------------------------------------------------+ + |``publicSshKey`` | string | | + +----------------------+--------+------------------------------------------------+ + |``registrationSent`` | string | | + +----------------------+--------+------------------------------------------------+ + |``role`` | string | | + +----------------------+--------+------------------------------------------------+ + |``roleName`` | string | | + +----------------------+--------+------------------------------------------------+ + |``stateOrProvince`` | string | | + +----------------------+--------+------------------------------------------------+ + |``uid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``username`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "addressLine1": "", + "addressLine2": "", + "city": "", + "company": "", + "country": "", + "email": "ema...@email.com", + "fullName": "Tom Simpson", + "gid": "0", + "id": "53", + "lastUpdated": "2016-01-26 10:22:07", + "newUser": true, + "phoneNumber": "", + "postalCode": "", + "publicSshKey": "xxx", + "registrationSent": true, + "role": "6", + "rolename": "admin", + "stateOrProvince": "", + "uid": "0", + "username": "tsimpson" + }, + { + ... more users + }, + ] + } + +| + + +**GET /api/1.1/users/:id** + + Retrieves user by ID. + + Authentication Required: Yes + + Role(s) Required: None + + **Request Route Parameters** + + +-----------+----------+---------------------------------------------+ + | Name | Required | Description | + +===========+==========+=============================================+ + | ``id`` | yes | User id. | + +-----------+----------+---------------------------------------------+ + + **Response Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``addressLine1`` | string | | + +----------------------+--------+------------------------------------------------+ + |``addressLine2`` | string | | + +----------------------+--------+------------------------------------------------+ + |``city`` | string | | + +----------------------+--------+------------------------------------------------+ + |``company`` | string | | + +----------------------+--------+------------------------------------------------+ + |``country`` | string | | + +----------------------+--------+------------------------------------------------+ + |``email`` | string | | + +----------------------+--------+------------------------------------------------+ + |``fullName`` | string | | + +----------------------+--------+------------------------------------------------+ + |``gid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``id`` | hash | | + +----------------------+--------+------------------------------------------------+ + |``lastUpdated`` | string | | + +----------------------+--------+------------------------------------------------+ + |``newUser`` | string | | + +----------------------+--------+------------------------------------------------+ + |``phoneNumber`` | string | | + +----------------------+--------+------------------------------------------------+ + |``postalCode`` | string | | + +----------------------+--------+------------------------------------------------+ + |``publicSshKey`` | string | | + +----------------------+--------+------------------------------------------------+ + |``registrationSent`` | string | | + +----------------------+--------+------------------------------------------------+ + |``role`` | string | | + +----------------------+--------+------------------------------------------------+ + |``roleName`` | string | | + +----------------------+--------+------------------------------------------------+ + |``stateOrProvince`` | string | | + +----------------------+--------+------------------------------------------------+ + |``uid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``username`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "addressLine1": "", + "addressLine2": "", + "city": "", + "company": "", + "country": "", + "email": "ema...@email.com", + "fullName": "Tom Simpson", + "gid": "0", + "id": "53", + "lastUpdated": "2016-01-26 10:22:07", + "newUser": true, + "phoneNumber": "", + "postalCode": "", + "publicSshKey": "xxx", + "registrationSent": true, + "role": "6", + "rolename": "admin", + "stateOrProvince": "", + "uid": "0", + "username": "tsimpson" + } + ] + } + +| + + +**GET /api/1.1/user/current** + + Retrieves the profile for the authenticated user. + + Authentication Required: Yes + + Role(s) Required: None + + **Request Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``email`` | string | | + +----------------------+--------+------------------------------------------------+ + |``city`` | string | | + +----------------------+--------+------------------------------------------------+ + |``id`` | string | | + +----------------------+--------+------------------------------------------------+ + |``phoneNumber`` | string | | + +----------------------+--------+------------------------------------------------+ + |``company`` | string | | + +----------------------+--------+------------------------------------------------+ + |``country`` | string | | + +----------------------+--------+------------------------------------------------+ + |``fullName`` | string | | + +----------------------+--------+------------------------------------------------+ + |``localUser`` | boolean| | + +----------------------+--------+------------------------------------------------+ + |``uid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``stateOrProvince`` | string | | + +----------------------+--------+------------------------------------------------+ + |``username`` | string | | + +----------------------+--------+------------------------------------------------+ + |``newUser`` | boolean| | + +----------------------+--------+------------------------------------------------+ + |``addressLine2`` | string | | + +----------------------+--------+------------------------------------------------+ + |``role`` | string | | + +----------------------+--------+------------------------------------------------+ + |``addressLine1`` | string | | + +----------------------+--------+------------------------------------------------+ + |``gid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``postalCode`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Response Example** :: + + { + "response": { + "email": "em...@email.com", + "city": "", + "id": "50", + "phoneNumber": "", + "company": "", + "country": "", + "fullName": "Tom Callahan", + "localUser": true, + "uid": "0", + "stateOrProvince": "", + "username": "tommyboy", + "newUser": false, + "addressLine2": "", + "role": "6", + "addressLine1": "", + "gid": "0", + "postalCode": "" + }, + } + +| + +**POST /api/1.1/user/current/update** + + Updates the date for the authenticated user. + + Authentication Required: Yes + + Role(s) Required: None + + **Request Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``email`` | string | | + +----------------------+--------+------------------------------------------------+ + |``city`` | string | | + +----------------------+--------+------------------------------------------------+ + |``id`` | string | | + +----------------------+--------+------------------------------------------------+ + |``phoneNumber`` | string | | + +----------------------+--------+------------------------------------------------+ + |``company`` | string | | + +----------------------+--------+------------------------------------------------+ + |``country`` | string | | + +----------------------+--------+------------------------------------------------+ + |``fullName`` | string | | + +----------------------+--------+------------------------------------------------+ + |``localUser`` | boolean| | + +----------------------+--------+------------------------------------------------+ + |``uid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``stateOrProvince`` | string | | + +----------------------+--------+------------------------------------------------+ + |``username`` | string | | + +----------------------+--------+------------------------------------------------+ + |``newUser`` | boolean| | + +----------------------+--------+------------------------------------------------+ + |``addressLine2`` | string | | + +----------------------+--------+------------------------------------------------+ + |``role`` | string | | + +----------------------+--------+------------------------------------------------+ + |``addressLine1`` | string | | + +----------------------+--------+------------------------------------------------+ + |``gid`` | string | | + +----------------------+--------+------------------------------------------------+ + |``postalCode`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Request Example** :: + + { + "user": { + "email": "", + "city": "", + "id": "", + "phoneNumber": "", + "company": "", + "country": "", + "fullName": "", + "localUser": true, + "uid": "0", + "stateOrProvince": "", + "username": "tommyboy", + "newUser": false, + "addressLine2": "", + "role": "6", + "addressLine1": "", + "gid": "0", + "postalCode": "" + } + } + + **Response Properties** + + +-------------+--------+----------------------------------+ + | Parameter | Type | Description | + +=============+========+==================================+ + | ``alerts`` | array | A collection of alert messages. | + +-------------+--------+----------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +-------------+--------+----------------------------------+ + | ``>text`` | string | Alert message. | + +-------------+--------+----------------------------------+ + | ``version`` | string | | + +-------------+--------+----------------------------------+ + + **Response Example** :: + + { + "alerts": [ + { + "level": "success", + "text": "UserProfile was successfully updated." + } + ], + } + +| + +**GET /api/1.1/user/current/jobs.json** + + Retrieves the user's list of jobs. + + Authentication Required: Yes + + Role(s) Required: None + + **Request Query Parameters** + + +--------------+----------+----------------------------------------+ + | Name | Required | Description | + +==============+==========+========================================+ + | ``keyword`` | no | PURGE | + +--------------+----------+----------------------------------------+ + + **Response Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``keyword`` | string | | + +----------------------+--------+------------------------------------------------+ + |``objectName`` | string | | + +----------------------+--------+------------------------------------------------+ + |``assetUrl`` | string | | + +----------------------+--------+------------------------------------------------+ + |``assetType`` | string | | + +----------------------+--------+------------------------------------------------+ + |``status`` | string | | + +----------------------+--------+------------------------------------------------+ + |``dsId`` | string | | + +----------------------+--------+------------------------------------------------+ + |``dsXmlId`` | string | | + +----------------------+--------+------------------------------------------------+ + |``username`` | boolean| | + +----------------------+--------+------------------------------------------------+ + |``parameters`` | string | | + +----------------------+--------+------------------------------------------------+ + |``enteredTime`` | string | | + +----------------------+--------+------------------------------------------------+ + |``objectType`` | string | | + +----------------------+--------+------------------------------------------------+ + |``agent`` | string | | + +----------------------+--------+------------------------------------------------+ + |``id`` | string | | + +----------------------+--------+------------------------------------------------+ + |``startTime`` | string | | + +----------------------+--------+------------------------------------------------+ + |``version`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Response Example** + :: + + { + "response": [ + { + "id": "1", + "keyword": "PURGE", + "objectName": null, + "assetUrl": "", + "assetType": "file", + "status": "PENDING", + "dsId": "9999", + "dsXmlId": "ds-xml-id", + "username": "peewee", + "parameters": "TTL:56h", + "enteredTime": "2015-01-21 18:00:16", + "objectType": null, + "agent": "", + "startTime": "2015-01-21 10:45:38" + } + ], + } + + +| + +**POST/api/1.1/user/current/jobs** + +Invalidating content on the CDN is sometimes necessary when the origin was mis-configured and something is cached in the CDN that needs to be removed. Given the size of a typical Traffic Control CDN and the amount of content that can be cached in it, removing the content from all the caches may take a long time. To speed up content invalidation, Traffic Ops will not try to remove the content from the caches, but it makes the content inaccessible using the *regex_revalidate* ATS plugin. This forces a *revalidation* of the content, rather than a new get. + +.. Note:: This method forces a HTTP *revalidation* of the content, and not a new *GET* - the origin needs to support revalidation according to the HTTP/1.1 specification, and send a ``200 OK`` or ``304 Not Modified`` as applicable. + +Authentication Required: Yes + +Role(s) Required: Yes + + **Request Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``dsId`` | string | Unique Delivery Service ID | + +----------------------+--------+------------------------------------------------+ + |``regex`` | string | Path Regex this should be a | + | | | `PCRE <http://www.pcre.org/>`_ compatible | + | | | regular expression for the path to match for | + | | | forcing the revalidation. Be careful to only | + | | | match on the content you need to remove - | + | | | revalidation is an expensive operation for | + | | | many origins, and a simple ``/.*`` can cause | + | | | an overload condition of the origin. | + +----------------------+--------+------------------------------------------------+ + |``startTime`` | string | Start Time is the time when the revalidation | + | | | rule will be made active. Populate | + | | | with the current time to schedule ASAP. | + +----------------------+--------+------------------------------------------------+ + |``ttl`` | int | Time To Live is how long the revalidation rule | + | | | will be active for in hours. It usually makes | + | | | sense to make this the same as the | + | | | ``Cache-Control`` header from the origin which | + | | | sets the object time to live in cache | + | | | (by ``max-age`` or ``Expires``). Entering a | + | | | longer TTL here will make the caches do | + | | | unnecessary work. | + +----------------------+--------+------------------------------------------------+ + + **Request Example** :: + + { + "dsId": "9999", + "regex": "/path/to/content.jpg", + "startTime": "2015-01-27 11:08:37", + "ttl": 54 + } + +| + + **Response Properties** + + +-------------+--------+----------------------------------+ + | Parameter | Type | Description | + +=============+========+==================================+ + | ``alerts`` | array | A collection of alert messages. | + +-------------+--------+----------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +-------------+--------+----------------------------------+ + | ``>text`` | string | Alert message. | + +-------------+--------+----------------------------------+ + | ``version`` | string | | + +-------------+--------+----------------------------------+ + + **Response Example** :: + + { + "alerts": + [ + { + "level": "success", + "text": "Successfully created purge job for: ." + } + ], + } + + +| + +**POST /api/1.1/user/login** + + Authentication of a user using username and password. Traffic Ops will send back a session cookie. + + Authentication Required: No + + Role(s) Required: None + + **Request Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``u`` | string | username | + +----------------------+--------+------------------------------------------------+ + |``p`` | string | password | + +----------------------+--------+------------------------------------------------+ + + **Request Example** :: + + { + "u": "username", + "p": "password" + } + +| + + **Response Properties** + + +-------------+--------+----------------------------------+ + | Parameter | Type | Description | + +=============+========+==================================+ + | ``alerts`` | array | A collection of alert messages. | + +-------------+--------+----------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +-------------+--------+----------------------------------+ + | ``>text`` | string | Alert message. | + +-------------+--------+----------------------------------+ + | ``version`` | string | | + +-------------+--------+----------------------------------+ + + **Response Example** :: + + { + "alerts": [ + { + "level": "success", + "text": "Successfully logged in." + } + ], + } + +| + +**GET /api/1.1/user/:id/deliveryservices/available.json** + + Authentication Required: Yes + + Role(s) Required: None + + **Request Route Parameters** + + +-----------------+----------+---------------------------------------------------+ + | Name | Required | Description | + +=================+==========+===================================================+ + |id | yes | | + +-----------------+----------+---------------------------------------------------+ + + **Response Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``xmlId`` | string | | + +----------------------+--------+------------------------------------------------+ + |``id`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "xmlId": "ns-img", + "id": "90" + }, + { + "xmlId": "ns-img-secure", + "id": "280" + } + ], + } + +| + +**POST /api/1.1/user/login/token** + + Authentication of a user using a token. + + Authentication Required: No + + Role(s) Required: None + + **Request Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``t`` | string | token-value | + +----------------------+--------+------------------------------------------------+ + + **Request Example** :: + + { + "t": "token-value" + } + +| + + **Response Properties** + + +-------------+--------+-------------+ + | Parameter | Type | Description | + +=============+========+=============+ + | ``alerts`` | array | | + +-------------+--------+-------------+ + | ``>level`` | string | | + +-------------+--------+-------------+ + | ``>text`` | string | | + +-------------+--------+-------------+ + | ``version`` | string | | + +-------------+--------+-------------+ + + **Response Example** :: + + { + "alerts": [ + { + "level": "error", + "text": "Unauthorized, please log in." + } + ], + } + +| + +**POST /api/1.1/user/logout** + + User logout. Invalidates the session cookie. + + Authentication Required: Yes + + Role(s) Required: None + + **Response Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``alerts`` | array | | + +----------------------+--------+------------------------------------------------+ + |* ``level`` | string | | + +----------------------+--------+------------------------------------------------+ + |* ``text`` | string | | + +----------------------+--------+------------------------------------------------+ + |``version`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Response Example** + + :: + + { + "alerts": [ + { + "level": "success", + "text": "You are logged out." + } + ], + } + + +| + +**POST /api/1.1/user/reset_password** + + Reset user password. + + Authentication Required: No + + Role(s) Required: None + + **Request Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``email`` | string | The email address of the user to initiate | + | | | password reset. | + +----------------------+--------+------------------------------------------------+ + + **Request Example** + :: + + { + "email": "em...@email.com" + } + +| + + **Response Properties** + + +----------------------+--------+------------------------------------------------+ + | Parameter | Type | Description | + +======================+========+================================================+ + |``alerts`` | array | A collection of alert messages. | + +----------------------+--------+------------------------------------------------+ + |* ``level`` | string | Success, info, warning or error. | + +----------------------+--------+------------------------------------------------+ + |* ``text`` | string | Alert message. | + +----------------------+--------+------------------------------------------------+ + |``version`` | string | | + +----------------------+--------+------------------------------------------------+ + + **Response Example** :: + + + + { + "alerts": [ + { + "level": "success", + "text": "Successfully sent password reset to email 'em...@email.com'" + } + ], + } + +
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/2ca12610/docs/master/_sources/api/v12/api_capability.rst.txt ---------------------------------------------------------------------- diff --git a/docs/master/_sources/api/v12/api_capability.rst.txt b/docs/master/_sources/api/v12/api_capability.rst.txt new file mode 100644 index 0000000..794dd4f --- /dev/null +++ b/docs/master/_sources/api/v12/api_capability.rst.txt @@ -0,0 +1,320 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + +.. _to-api-v12-api_capability: + +API-Capabilities +================ + +.. _to-api-v12-api-capability-route: + +/api/1.2/api_capabilities ++++++++++++++++++++++++++ + +**GET /api/1.2/api_capabilities** + + Get all API-capability mappings. + + Authentication Required: Yes + + Role(s) Required: None + + **Query Parameters** + + +----------------+----------+--------+------------------------------------+ + | Name | Required | Type | Description | + +================+==========+========+====================================+ + | ``capability`` | no | string | Capability name. | + +----------------+----------+--------+------------------------------------+ + + **Response Properties** + + +-------------------+--------+--------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+==================================================+ + | ``id`` | int | Mapping id. | + +-------------------+--------+--------------------------------------------------+ + | ``httpMethod`` | enum | One of: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'. | + +-------------------+--------+--------------------------------------------------+ + | ``route`` | string | API route. | + +-------------------+--------+--------------------------------------------------+ + | ``capability`` | string | Capability name. | + +-------------------+--------+--------------------------------------------------+ + | ``lastUpdated`` | string | | + +-------------------+--------+--------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "id": "6", + "httpMethod": "GET", + "route": "/api/*/asns", + "capability": "asn-read", + "lastUpdated": "2017-04-02 08:22:43" + }, + { + "id": "7", + "httpMethod": "GET", + "route": "/api/*/asns/*", + "capability": "asn-read", + "lastUpdated": "2017-04-02 08:22:43" + } + ] + } + +| + +**GET /api/1.2/api_capabilities/:id** + + Get an API-capability mapping by id. + + Authentication Required: Yes + + Role(s) Required: None + + **Request Route Parameters** + + +-------------+----------+-------+-------------------------------------+ + | Name | Required | Type | Description | + +=============+==========+=======+=====================================+ + | ``id`` | yes | int | Mapping id. | + +-------------+----------+-------+-------------------------------------+ + + **Response Properties** + + +-------------------+--------+--------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+==================================================+ + | ``id`` | int | Mapping id. | + +-------------------+--------+--------------------------------------------------+ + | ``httpMethod`` | enum | One of: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'. | + +-------------------+--------+--------------------------------------------------+ + | ``route`` | string | API route. | + +-------------------+--------+--------------------------------------------------+ + | ``capability`` | string | Capability name. | + +-------------------+--------+--------------------------------------------------+ + | ``lastUpdated`` | string | | + +-------------------+--------+--------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "id": "6", + "httpMethod": "GET", + "route": "/api/*/asns", + "capability": "asn-read", + "lastUpdated": "2017-04-02 08:22:43" + } + ] + } + +| + +**POST /api/1.2/api_capabilities** + + Create an API-capability mapping. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Properties** + + +----------------+----------+--------+--------------------------------------------------+ + | Name | Required | Type | Description | + +================+==========+========+==================================================+ + | ``httpMethod`` | yes | enum | One of: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'. | + +----------------+----------+--------+--------------------------------------------------+ + | ``route`` | yes | string | API route. | + +----------------+----------+--------+--------------------------------------------------+ + | ``capability`` | yes | string | Capability name | + +----------------+----------+--------+--------------------------------------------------+ + + **Request Example** :: + + { + "httpMethod": "POST", + "route": "/api/*/cdns", + "capability": "cdn-write" + } + + **Response Properties** + + +--------------------+--------+--------------------------------------------------+ + | Parameter | Type | Description | + +====================+========+==================================================+ + | ``response`` | hash | The details of the creation, if success. | + +--------------------+--------+--------------------------------------------------+ + | ``>id`` | int | Mapping id. | + +--------------------+--------+--------------------------------------------------+ + | ``>httpMethod`` | enum | One of: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'. | + +--------------------+--------+--------------------------------------------------+ + | ``>route`` | string | API route. | + +--------------------+--------+--------------------------------------------------+ + | ``>capability`` | string | Capability name | + +--------------------+--------+--------------------------------------------------+ + | ``>lastUpdated`` | string | | + +--------------------+--------+--------------------------------------------------+ + | ``alerts`` | array | A collection of alert messages. | + +--------------------+--------+--------------------------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +--------------------+--------+--------------------------------------------------+ + | ``>text`` | string | Alert message. | + +--------------------+--------+--------------------------------------------------+ + + + **Response Example** :: + + { + "response":{ + "id": "6", + "httpMethod": "POST", + "route": "/api/*/cdns", + "capability": "cdn-write", + "lastUpdated": "2017-04-02 08:22:43" + }, + "alerts":[ + { + "level": "success", + "text": "API-capability mapping was created." + } + ] + } + +| + +**PUT /api/1.2/api_capabilities/{:id}** + + Edit an API-capability mapping. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Route Parameters** + + +-------------------+----------+--------+---------------------------------------+ + | Name | Required | Type | Description | + +===================+==========+========+=======================================+ + | ``id`` | yes | string | Mapping id. | + +-------------------+----------+--------+---------------------------------------+ + + **Request Properties** + + +-------------------+--------+--------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+==================================================+ + | ``httpMethod`` | enum | One of: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'. | + +-------------------+--------+--------------------------------------------------+ + | ``route`` | string | API route. | + +-------------------+--------+--------------------------------------------------+ + | ``capability`` | string | Capability name | + +-------------------+--------+--------------------------------------------------+ + + + **Request Example** :: + + { + "httpMethod": "GET", + "route": "/api/*/cdns", + "capability": "cdn-read" + } + + **Response Properties** + + +--------------------+--------+--------------------------------------------------+ + | Parameter | Type | Description | + +====================+========+==================================================+ + | ``response`` | hash | The details of the creation, if success. | + +--------------------+--------+--------------------------------------------------+ + | ``>id`` | int | Mapping id. | + +--------------------+--------+--------------------------------------------------+ + | ``>httpMethod`` | enum | One of: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'. | + +--------------------+--------+--------------------------------------------------+ + | ``>route`` | string | API route. | + +--------------------+--------+--------------------------------------------------+ + | ``>capability`` | string | Capability name | + +--------------------+--------+--------------------------------------------------+ + | ``>lastUpdated`` | string | | + +--------------------+--------+--------------------------------------------------+ + | ``alerts`` | array | A collection of alert messages. | + +--------------------+--------+--------------------------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +--------------------+--------+--------------------------------------------------+ + | ``>text`` | string | Alert message. | + +--------------------+--------+--------------------------------------------------+ + + **Response Example** :: + + { + "response":{ + "id": "6", + "httpMethod": "GET", + "route": "/api/*/cdns", + "capability": "cdn-read", + "lastUpdated": "2017-04-02 08:22:43" + }, + "alerts":[ + { + "level": "success", + "text": "API-capability mapping was updated." + } + ] + } + +| + +**DELETE /api/1.2/api_capabilities/{:id}** + + Delete a capability. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Route Parameters** + + +-------------------+----------+--------+---------------------------------------+ + | Name | Required | Type | Description | + +===================+==========+========+=======================================+ + | ``id`` | yes | string | Mapping id. | + +-------------------+----------+--------+---------------------------------------+ + + **Response Properties** + + +-----------------+----------+------------------------------------------------+ + | Parameter | Type | Description | + +=================+==========+================================================+ + | ``alerts`` | array | A collection of alert messages. | + +-----------------+----------+------------------------------------------------+ + | ``>level`` | string | success, info, warning or error. | + +-----------------+----------+------------------------------------------------+ + | ``>text`` | string | Alert message. | + +-----------------+----------+------------------------------------------------+ + + **Response Example** :: + + { + "alerts": [ + { + "level": "success", + "text": "API-capability mapping deleted." + } + ], + } http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/2ca12610/docs/master/_sources/api/v12/asn.rst.txt ---------------------------------------------------------------------- diff --git a/docs/master/_sources/api/v12/asn.rst.txt b/docs/master/_sources/api/v12/asn.rst.txt new file mode 100644 index 0000000..b5803cd --- /dev/null +++ b/docs/master/_sources/api/v12/asn.rst.txt @@ -0,0 +1,200 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + + +.. _to-api-v12-asn: + +ASN +=== + +.. _to-api-v12-asns-route: + +/api/1.2/asns ++++++++++++++ + +**GET /api/1.2/asns** + + Authentication Required: Yes + + Role(s) Required: None + + **Request Query Parameters** + + +---------------------+----------+---------------------------------------------+ + | Name | Required | Description | + +=====================+==========+=============================================+ + | ``cachegroup`` | no | Filter ASNs by cache group ID | + +---------------------+----------+---------------------------------------------+ + + **Response Properties** + + +------------------+--------+-------------------------------------------------------------------------+ + | Parameter | Type | Description | + +==================+========+=========================================================================+ + | ``lastUpdated`` | string | The Time / Date this server entry was last updated | + +------------------+--------+-------------------------------------------------------------------------+ + | ``id`` | string | Local unique identifier for the ASN | + +------------------+--------+-------------------------------------------------------------------------+ + | ``asn`` | string | Autonomous System Numbers per APNIC for identifying a service provider. | + +------------------+--------+-------------------------------------------------------------------------+ + | ``cachegroup`` | string | Related cachegroup name | + +------------------+--------+-------------------------------------------------------------------------+ + | ``cachegroupId`` | string | Related cachegroup id | + +------------------+--------+-------------------------------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "lastUpdated": "2012-09-17 21:41:22", + "id": "27", + "asn": "7015", + "cachegroup": "us-ma-woburn", + "cachegroupId": "27", + }, + { + "lastUpdated": "2012-09-17 21:41:22", + "id": "28", + "asn": "7016", + "cachegroup": "us-pa-pittsburgh", + "cachegroupId": "13" + } + ] + } + +| + +**GET /api/1.2/asns/:id** + + Authentication Required: Yes + + Role(s) Required: None + + **Request Route Parameters** + + +-----------+----------+---------------------------------------------+ + | Name | Required | Description | + +===========+==========+=============================================+ + | ``id`` | yes | ASN id. | + +-----------+----------+---------------------------------------------+ + + **Response Properties** + + +------------------+--------+-------------------------------------------------------------------------+ + | Parameter | Type | Description | + +==================+========+=========================================================================+ + | ``lastUpdated`` | string | The Time / Date this server entry was last updated | + +------------------+--------+-------------------------------------------------------------------------+ + | ``id`` | string | Local unique identifier for the ASN | + +------------------+--------+-------------------------------------------------------------------------+ + | ``asn`` | string | Autonomous System Numbers per APNIC for identifying a service provider. | + +------------------+--------+-------------------------------------------------------------------------+ + | ``cachegroup`` | string | Related cachegroup name | + +------------------+--------+-------------------------------------------------------------------------+ + | ``cachegroupId`` | string | Related cachegroup id | + +------------------+--------+-------------------------------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "lastUpdated": "2012-09-17 21:41:22", + "id": "28", + "asn": "7016", + "cachegroup": "us-pa-pittsburgh", + "cachegroupId": "13" + } + ] + } + +| + +**PUT /api/1.2/asns/{:id}** + + Allows user to edit an ASN. + + Authentication Required: Yes + + Role(s) Required: admin or oper + + **Request Route Parameters** + + +-------------------+----------+------------------------------------------------+ + | Name | Type | Description | + +===================+==========+================================================+ + | ``id`` | int | ASN id. | + +-------------------+----------+------------------------------------------------+ + + **Request Properties** + + +-------------------+--------+-------------------------------------------------+ + | Parameter | Type | Description | + +===================+========+=================================================+ + | ``asn`` | string | ASN | + +-------------------+--------+-------------------------------------------------+ + | ``cachegroupId`` | string | The cachegroup the ASN belongs to | + +-------------------+--------+-------------------------------------------------+ + + + **Request Example** :: + + { + "asn": "99", + "cachegroupId": "177" + } + + **Response Properties** + + +--------------------+--------+-------------------------------------------------+ + | Parameter | Type | Description | + +====================+========+=================================================+ + | ``response`` | hash | The details of the update, if success. | + +--------------------+--------+-------------------------------------------------+ + | ``>name`` | string | CDN name. | + +--------------------+--------+-------------------------------------------------+ + | ``>id`` | int | CDN id. | + +--------------------+--------+-------------------------------------------------+ + | ``>dnssecEnabled`` | string | Whether dnssec is enabled. | + +--------------------+--------+-------------------------------------------------+ + | ``alerts`` | array | A collection of alert messages. | + +--------------------+--------+-------------------------------------------------+ + | ``>level`` | string | Success, info, warning or error. | + +--------------------+--------+-------------------------------------------------+ + | ``>text`` | string | Alert message. | + +--------------------+--------+-------------------------------------------------+ + + **Response Example** :: + + { + "response":{ + "lastUpdated": "2012-09-17 21:41:22", + "id": "28", + "asn": "99", + "cachegroup": "us-pa-pittsburgh", + "cachegroupId": "177" + }, + "alerts":[ + { + "level": "success", + "text": "cdn was updated." + } + ] + } + +| + + http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/2ca12610/docs/master/_sources/api/v12/cache.rst.txt ---------------------------------------------------------------------- diff --git a/docs/master/_sources/api/v12/cache.rst.txt b/docs/master/_sources/api/v12/cache.rst.txt new file mode 100644 index 0000000..f56b46c --- /dev/null +++ b/docs/master/_sources/api/v12/cache.rst.txt @@ -0,0 +1,84 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + + +.. _to-api-v12-cache: + +Cache +===== + +.. _to-api-v12-cache-route: + +/api/1.2/caches/stats ++++++++++++++++++++++ + +**GET /api/1.2/caches/stats** + + Retrieves cache stats from Traffic Monitor. Also includes rows for aggregates. + + Authentication Required: Yes + + Role(s) Required: None + + **Response Properties** + + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +============================+===============+=========================================================================================+ + |``profile`` | string | The profile of the cache. | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``cachegroup`` | string | The cache group of the cache. | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``hostname`` | string | The hostname of the cache. | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``ip`` | string | The IP address of the cache. | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``status`` | string | The status of the cache. | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``healthy`` | string | Has Traffic Monitor marked the cache as healthy or unhealthy? | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``connections`` | string | Cache connections | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``kbps`` | string | Cache kbps out | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + + **Response Example** :: + + { + "response": [ + { + "profile": "ALL", + "cachegroup": "ALL", + "hostname": "ALL", + "ip": null, + "status": "ALL", + "healthy": true, + "connections": 934424, + "kbps": 618631875 + }, + { + "profile": "EDGE1_FOO_721-ATS621-45", + "cachegroup": "us-nm-albuquerque", + "hostname": "foo-bar-alb-01", + "ip": "2.2.2.2", + "status": "REPORTED", + "healthy": true, + "connections": 373, + "kbps": 390136 + }, + ] + } + +| http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/2ca12610/docs/master/_sources/api/v12/cache_stats.rst.txt ---------------------------------------------------------------------- diff --git a/docs/master/_sources/api/v12/cache_stats.rst.txt b/docs/master/_sources/api/v12/cache_stats.rst.txt new file mode 100644 index 0000000..dffc9a4 --- /dev/null +++ b/docs/master/_sources/api/v12/cache_stats.rst.txt @@ -0,0 +1,134 @@ +.. +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. + + +.. _to-api-v12-cache-stats: + +Cache Statistics +=========================== + +.. _to-api-v12-cache-stats-route: + +/api/1.2/cache_stats +++++++++++++++++++++ + +**GET /api/1.2/cache_stats.json** + + Retrieves statistics about the CDN. + + Authentication Required: Yes + + Role(s) Required: None + + **Request Query Parameters** + + +--------------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Required | Description | + +==========================+==========+==============================================================================================================================================+ + | ``cdnName`` | yes | The CDN name to return cache stats for | + +--------------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | ``metricType`` | yes | The metric type (valid metric types: 'ats.proxy.process.http.current_client_connections', 'bandwidth', 'maxKbps') | + +--------------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | ``startDate`` | yes | The begin date (Formatted as ISO8601, for example: '2015-08-11T12:30:00-06:00') | + +--------------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | ``endDate`` | yes | The end date (Formatted as ISO8601, for example: '2015-08-12T12:30:00-06:00') | + +--------------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------+ + + **Response Properties** + + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + | Parameter | Type | Description | + +============================+===============+=========================================================================================+ + |``summary`` | hash | Summary data | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>count`` | int | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>min`` | float | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>max`` | float | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>fifthPercentile`` | float | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>ninetyEighthPercentile`` | float | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>ninetyFifthPercentile`` | float | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>average`` | float | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``series`` | hash | Series data | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>count`` | int | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>columns`` | array | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>name`` | string | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>values`` | array | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>>time`` | string | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + |``>>value`` | float | | + +----------------------------+---------------+-----------------------------------------------------------------------------------------+ + + **Response Example** :: + + { + "response": { + "series": { + "columns": [ + "time", + "" + ], + "count": 29, + "name": "bandwidth", + "tags": { + "cdn": "over-the-top" + }, + "values": [ + [ + "2015-08-10T22:40:00Z", + 229340299720 + ], + [ + "2015-08-10T22:41:00Z", + 224309221713.334 + ], + [ + "2015-08-10T22:42:00Z", + 229551834168.334 + ], + [ + "2015-08-10T22:43:00Z", + 225179658876.667 + ], + [ + "2015-08-10T22:44:00Z", + 230443968275 + ] + ] + }, + "summary": { + "average": 970410.295, + "count": 1376041798, + "fifthPercentile": 202.03, + "max": 3875441.02, + "min": 0, + "ninetyEighthPercentile": 2957940.93, + "ninetyFifthPercentile": 2366728.63 + } + } + } + +|
