| .. |
| .. |
| .. 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": "email1@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": "email1@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": "email@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": "email@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 'email@email.com'" |
| } |
| ], |
| } |
| |
| |