You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by de...@apache.org on 2018/05/24 15:31:27 UTC
[incubator-trafficcontrol] 05/08: Add Origin API reference docs
This is an automated email from the ASF dual-hosted git repository.
dewrich pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-trafficcontrol.git
commit f02231702a958004c72a1a5b62e305aae4e80a57
Author: Rawlin Peters <ra...@comcast.com>
AuthorDate: Tue May 8 15:11:13 2018 -0600
Add Origin API reference docs
---
docs/source/api/v13/index.rst | 1 +
docs/source/api/v13/origin.rst | 462 +++++++++++++++++++++++++++++++++++++++++
lib/go-tc/constants.go | 1 +
3 files changed, 464 insertions(+)
diff --git a/docs/source/api/v13/index.rst b/docs/source/api/v13/index.rst
index 4624560..6774909 100644
--- a/docs/source/api/v13/index.rst
+++ b/docs/source/api/v13/index.rst
@@ -22,3 +22,4 @@ Traffic Ops API V1.3
:maxdepth: 1
coordinate
+ origin
diff --git a/docs/source/api/v13/origin.rst b/docs/source/api/v13/origin.rst
new file mode 100644
index 0000000..31aad64
--- /dev/null
+++ b/docs/source/api/v13/origin.rst
@@ -0,0 +1,462 @@
+..
+..
+.. 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-v13-origin:
+
+Origin
+======
+
+.. _to-api-v13-origin-route:
+
+/api/1.3/origins
+++++++++++++++++
+
+**GET /api/1.3/origins**
+
+ Get Origins.
+
+ Authentication Required: Yes
+
+ Role(s) Required: None
+
+ **Request Query Parameters**
+
+ +-------------------------+-----------------+---------------------------------------------------+
+ | Name | Required | Description |
+ +=========================+=================+===================================================+
+ | ``cachegroup`` | no | Filter Origins by cachegroup ID. |
+ +-------------------------+-----------------+---------------------------------------------------+
+ | ``coordinate`` | no | Filter Origins by coordinate ID. |
+ +-------------------------+-----------------+---------------------------------------------------+
+ | ``deliveryservice`` | no | Filter Origins by deliveryservice ID. |
+ +-------------------------+-----------------+---------------------------------------------------+
+ | ``id`` | no | Filter Origins by ID. |
+ +-------------------------+-----------------+---------------------------------------------------+
+ | ``name`` | no | Filter Origins by name. |
+ +-------------------------+-----------------+---------------------------------------------------+
+ | ``profileId`` | no | Filter Origins by profile ID. |
+ +-------------------------+-----------------+---------------------------------------------------+
+ | ``tenant`` | no | Filter Origins by tenant ID. |
+ +-------------------------+-----------------+---------------------------------------------------+
+
+ **Response Properties**
+
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | Parameter | Type | Description |
+ +===================================+===================+==========================================================================+
+ | ``cachegroup`` | string | Name of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``cachegroupId`` | int | ID of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinate`` | string | Name of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinateID`` | int | ID of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryService`` | string | XML_ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryServiceId`` | int | ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``fqdn`` | string | The FQDN of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``id`` | int | Local unique identifier for the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ip6Address`` | string | IPv6 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ipAddress`` | string | IPv4 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``lastUpdated`` | string | The Time / Date this entry was last updated |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``name`` | string | The name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``port`` | int | The TCP port on which the Origin listens |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profile`` | string | The profile name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profileId`` | int | The profile ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``protocol`` | string | The protocol of the Origin's URL (http or https) |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenant`` | string | The tenant name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenantId`` | int | The tenant ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+
+ **Response Example** ::
+
+ {
+ "response": [
+ {
+ "cachegroup": "cg1",
+ "cachegroupId": 1,
+ "coordinate": "coordinate1",
+ "coordinateId": 1,
+ "deliveryService": "myds",
+ "deliveryServiceId": 1,
+ "fqdn": "example.com",
+ "id": 1,
+ "ip6Address": "cafe:dead:d0d0::42",
+ "ipAddress": "10.2.3.4",
+ "lastUpdated": "2018-05-08 19:33:18+00",
+ "name": "my-origin",
+ "port": 443,
+ "profile": "my-origins",
+ "profileId": 1,
+ "protocol": "https",
+ "tenant": "tenantA",
+ "tenantId": 3
+ },
+ {
+ "cachegroup": null,
+ "cachegroupId": null,
+ "coordinate": null,
+ "coordinateId": null,
+ "deliveryService": null,
+ "deliveryServiceId": null,
+ "fqdn": "foo.example.com",
+ "id": 2,
+ "ip6Address": null,
+ "ipAddress": null,
+ "lastUpdated": "2018-05-08 19:35:12+00",
+ "name": "origin2",
+ "port": null,
+ "profile": null,
+ "profileId": null,
+ "protocol": "http",
+ "tenant": null,
+ "tenantId": null
+ }
+ ]
+ }
+
+|
+
+**POST /api/1.3/origins**
+
+ Create Origin.
+
+ Authentication Required: Yes
+
+ Role(s) Required: admin or oper
+
+ **Request Parameters**
+
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +===================================+===================+==========================================================================+
+ | ``cachegroupId`` | no | ID of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinateID`` | no | ID of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryServiceId`` | no | ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``fqdn`` | yes | The FQDN of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ip6Address`` | no | IPv6 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ipAddress`` | no | IPv4 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``name`` | yes | The name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``port`` | no | The TCP port on which the Origin listens |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profileId`` | no | The profile ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``protocol`` | yes | The protocol of the Origin's URL (http or https) |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenantId`` | no | The tenant ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+
+ **Request Example** ::
+
+ {
+ "cachegroupId": 1,
+ "coordinateId": 1,
+ "deliveryServiceId": 1,
+ "fqdn": "foo.example.com",
+ "ip6Address": "cafe:dead:d0d0::42",
+ "ipAddress": "10.2.3.4",
+ "name": "origin1",
+ "port": 443,
+ "profileId": 1,
+ "protocol": "https",
+ "tenantId": 1
+ }
+
+ **Response Properties**
+
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | Parameter | Type | Description |
+ +===================================+===================+==========================================================================+
+ | ``cachegroup`` | string | Name of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``cachegroupId`` | int | ID of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinate`` | string | Name of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinateID`` | int | ID of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryService`` | string | XML_ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryServiceId`` | int | ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``fqdn`` | string | The FQDN of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``id`` | int | Local unique identifier for the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ip6Address`` | string | IPv6 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ipAddress`` | string | IPv4 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``lastUpdated`` | string | The Time / Date this entry was last updated |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``name`` | string | The name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``port`` | int | The TCP port on which the Origin listens |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profile`` | string | The profile name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profileId`` | int | The profile ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``protocol`` | string | The protocol of the Origin's URL (http or https) |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenant`` | string | The tenant name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenantId`` | int | The tenant ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``alerts`` | array | A collection of alert messages. |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``>level`` | string | Success, info, warning or error. |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``>text`` | string | Alert message. |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+
+ **Response Example** ::
+
+ {
+ "alerts": [
+ {
+ "level": "success",
+ "text": "origin was created."
+ }
+ ],
+ "response": {
+ "cachegroup": null,
+ "cachegroupId": 1,
+ "coordinate": null,
+ "coordinateId": 1,
+ "deliveryService": null,
+ "deliveryServiceId": 1,
+ "fqdn": "foo.example.com",
+ "id": 1,
+ "ip6Address": "cafe:dead:d0d0::42",
+ "ipAddress": "10.2.3.4",
+ "lastUpdated": "2018-05-08 20:30:27+00",
+ "name": "origin1",
+ "port": 443,
+ "profile": null,
+ "profileId": 1,
+ "protocol": "https",
+ "tenant": null,
+ "tenantId": 1
+ }
+ }
+
+|
+
+**PUT /api/1.3/origins**
+
+ Update origin.
+
+ Authentication Required: Yes
+
+ Role(s) Required: admin or oper
+
+ **Request Query Parameters**
+
+ +------+----------+------------------------------------+
+ | Name | Required | Description |
+ +======+==========+====================================+
+ | id | yes | The id of the coordinate to edit. |
+ +------+----------+------------------------------------+
+
+ **Request Parameters**
+
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +===================================+===================+==========================================================================+
+ | ``cachegroupId`` | no | ID of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinateID`` | no | ID of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryServiceId`` | no | ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``fqdn`` | yes | The FQDN of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``id`` | yes | The ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ip6Address`` | no | IPv6 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ipAddress`` | no | IPv4 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``name`` | yes | The name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``port`` | no | The TCP port on which the Origin listens |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profileId`` | no | The profile ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``protocol`` | yes | The protocol of the Origin's URL (http or https) |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenantId`` | no | The tenant ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+
+ **Request Example** ::
+
+ {
+ "cachegroupId": 1,
+ "coordinateId": 1,
+ "deliveryServiceId": 1,
+ "fqdn": "foo.example.com",
+ "id": 1,
+ "ip6Address": "cafe:dead:d0d0::42",
+ "ipAddress": "10.2.3.4",
+ "name": "origin1",
+ "port": 443,
+ "profileId": 1,
+ "protocol": "https",
+ "tenantId": 1
+ }
+
+ **Response Properties**
+
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | Parameter | Type | Description |
+ +===================================+===================+==========================================================================+
+ | ``cachegroup`` | string | Name of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``cachegroupId`` | int | ID of the Origin's cachegroup |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinate`` | string | Name of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``coordinateID`` | int | ID of the Origin's coordinate |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryService`` | string | XML_ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``deliveryServiceId`` | int | ID of the Origin's delivery service |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``fqdn`` | string | The FQDN of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``id`` | int | Local unique identifier for the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ip6Address`` | string | IPv6 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``ipAddress`` | string | IPv4 address of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``lastUpdated`` | string | The Time / Date this entry was last updated |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``name`` | string | The name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``port`` | int | The TCP port on which the Origin listens |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profile`` | string | The profile name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``profileId`` | int | The profile ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``protocol`` | string | The protocol of the Origin's URL (http or https) |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenant`` | string | The tenant name of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``tenantId`` | int | The tenant ID of the Origin |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``alerts`` | array | A collection of alert messages. |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``>level`` | string | Success, info, warning or error. |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+ | ``>text`` | string | Alert message. |
+ +-----------------------------------+-------------------+--------------------------------------------------------------------------+
+
+ **Response Example** ::
+
+ {
+ "alerts": [
+ {
+ "level": "success",
+ "text": "origin was updated."
+ }
+ ],
+ "response": {
+ "cachegroup": null,
+ "cachegroupId": 1,
+ "coordinate": null,
+ "coordinateId": 1,
+ "deliveryService": null,
+ "deliveryServiceId": 1,
+ "fqdn": "foo.example.com",
+ "id": 1,
+ "ip6Address": "cafe:dead:d0d0::42",
+ "ipAddress": "10.2.3.4",
+ "lastUpdated": "2018-05-08 20:30:27+00",
+ "name": "origin1",
+ "port": 443,
+ "profile": null,
+ "profileId": 1,
+ "protocol": "https",
+ "tenant": null,
+ "tenantId": 1
+ }
+ }
+
+|
+
+**DELETE /api/1.3/origin**
+
+ Delete origin.
+
+ Authentication Required: Yes
+
+ Role(s) Required: admin or oper
+
+ **Request Query Parameters**
+
+ +------+----------+--------------------------------------+
+ | Name | Required | Description |
+ +======+==========+======================================+
+ | id | yes | The id of the origin to delete. |
+ +------+----------+--------------------------------------+
+
+ **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": "origin was deleted"
+ }
+ ]
+ }
+
+|
+
diff --git a/lib/go-tc/constants.go b/lib/go-tc/constants.go
index 35ae649..4f91944 100644
--- a/lib/go-tc/constants.go
+++ b/lib/go-tc/constants.go
@@ -26,6 +26,7 @@ func (e ErrorConstant) Error() string { return string(e) }
const DBError = ErrorConstant("database access error")
const NilTenantError = ErrorConstant("tenancy is enabled but request tenantID is nil")
const TenantUserNotAuthError = ErrorConstant("user not authorized for requested tenant")
+const TenantDSUserNotAuthError = ErrorConstant("user not authorized for requested delivery service tenant")
const ApplicationJson = "application/json"
const Gzip = "gzip"
--
To stop receiving notification emails like this one, please contact
dewrich@apache.org.