[GitHub] [trafficcontrol] ocket8888 opened a new pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

ocket8888 opened a new pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716


   ## What does this PR (Pull Request) do?
   - [x] This PR is not related to any Issue
   
   Adds the API guidelines previously merged in [a blueprint](https://github.com/apache/trafficcontrol/blob/master/blueprints/api.guidelines.md) to the official docs.
   
   
   ## Which Traffic Control components are affected by this PR?
   - Documentation
   
   ## What is the best way to verify this PR?
   No tests for docs; just build and read them.
   
   
   ## The following criteria are ALL met by this PR
   - [x] I have explained why tests are unnecessary
   - [x] This PR includes documentation
   - [x] An update to CHANGELOG.md is not necessary
   - [x] This PR includes any and all required license headers
   - [x] This PR does not include a database migration
   - x ] This PR **DOES NOT FIX A SERIOUS SECURITY VULNERABILITY**


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

ocket8888 commented on a change in pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716#discussion_r431336408



##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.
+
+HTTP Request Methods
+====================
+:RFC:`7231#section-4` defines the semantics of HTTP/1.1 request methods. Authors should conform to that set of standards whenever possible, but for convenience the methods recognized by Traffic Ops and their meanings in that context are herein defined.
+
+GET
+---
+HTTP GET requests are issued by clients who want some data in response. In the context of Traffic Ops, this generally means a serialized representation of some object. GET requests MUST NOT alter the state of the server. An example of an API endpoint created in API version 1 that violates this restriction is :samp:`cdns/name/{name}/dnsseckeys/delete`.
+
+This is the standard method to be used by all read-only operations, and as such handlers for this method should generally be accessible to users with the "read-only" :term:`Role`.
+
+All endpoints dealing with the manipulation or fetching representations of "Traffic Control Objects" MUST support this method.
+
+POST
+----
+POST requests ask the server to process some provided data. Most commonly, in Traffic Ops, this means creating an object based on the serialization of said object contained in the request body, but it can also be used virtually whenever no other method is appropriate. When an object *is* created, the response body MUST contain a representation of the newly created object. POST requests do not need to be *idempotent*, unlike PUT requests.
+
+PUT
+---
+PUT is used to replace existing data with new data that is provided in the request body. :RFC:`2616#section-9.1.2` lists PUT as an "idempotent" request method, which means that subsequent identical requests should ensure the same state is maintained on the server. What this means is that a client that PUTs an object representation to Traffic Ops expects that if they then GET a representation of that object, do the same PUT again and GET another representation, the two retrieved representations should be identical. Effectively, the ``lastUpdated`` field that is common to objects in the :ref:`to-api` violates this, but the other properties of objects - which can actually be defined - generally obey this restriction. In general, fulfilling this restriction means that handlers will need to require the entirety of an object be defined in the request body.
+
+When an object is replaced, the response body MUST contain a representation of the object after replacement. While :RFC:`2616` states that servers MAY create objects for the passed representations if they do not already exist, :ref:`to-api` endpoint authors MUST instead use POST handlers for object creation.
+
+All endpoints that support the PUT request method MUST also support the :mailheader:`If-Unmodified-Since` HTTP header.

Review comment:
       Yeah, I'll need to. Where is it?




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] mitchell852 commented on a change in pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

mitchell852 commented on a change in pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716#discussion_r431306372



##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.
+
+HTTP Request Methods
+====================
+:RFC:`7231#section-4` defines the semantics of HTTP/1.1 request methods. Authors should conform to that set of standards whenever possible, but for convenience the methods recognized by Traffic Ops and their meanings in that context are herein defined.
+
+GET
+---
+HTTP GET requests are issued by clients who want some data in response. In the context of Traffic Ops, this generally means a serialized representation of some object. GET requests MUST NOT alter the state of the server. An example of an API endpoint created in API version 1 that violates this restriction is :samp:`cdns/name/{name}/dnsseckeys/delete`.
+
+This is the standard method to be used by all read-only operations, and as such handlers for this method should generally be accessible to users with the "read-only" :term:`Role`.
+
+All endpoints dealing with the manipulation or fetching representations of "Traffic Control Objects" MUST support this method.
+
+POST
+----
+POST requests ask the server to process some provided data. Most commonly, in Traffic Ops, this means creating an object based on the serialization of said object contained in the request body, but it can also be used virtually whenever no other method is appropriate. When an object *is* created, the response body MUST contain a representation of the newly created object. POST requests do not need to be *idempotent*, unlike PUT requests.
+
+PUT
+---
+PUT is used to replace existing data with new data that is provided in the request body. :RFC:`2616#section-9.1.2` lists PUT as an "idempotent" request method, which means that subsequent identical requests should ensure the same state is maintained on the server. What this means is that a client that PUTs an object representation to Traffic Ops expects that if they then GET a representation of that object, do the same PUT again and GET another representation, the two retrieved representations should be identical. Effectively, the ``lastUpdated`` field that is common to objects in the :ref:`to-api` violates this, but the other properties of objects - which can actually be defined - generally obey this restriction. In general, fulfilling this restriction means that handlers will need to require the entirety of an object be defined in the request body.
+
+When an object is replaced, the response body MUST contain a representation of the object after replacement. While :RFC:`2616` states that servers MAY create objects for the passed representations if they do not already exist, :ref:`to-api` endpoint authors MUST instead use POST handlers for object creation.
+
+All endpoints that support the PUT request method MUST also support the :mailheader:`If-Unmodified-Since` HTTP header.

Review comment:
       so you're going to fix the `If-Not-Modified-Since` reference that i saw somewhere?




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

ocket8888 commented on a change in pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716#discussion_r431369254



##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.
+
+HTTP Request Methods
+====================
+:RFC:`7231#section-4` defines the semantics of HTTP/1.1 request methods. Authors should conform to that set of standards whenever possible, but for convenience the methods recognized by Traffic Ops and their meanings in that context are herein defined.
+
+GET
+---
+HTTP GET requests are issued by clients who want some data in response. In the context of Traffic Ops, this generally means a serialized representation of some object. GET requests MUST NOT alter the state of the server. An example of an API endpoint created in API version 1 that violates this restriction is :samp:`cdns/name/{name}/dnsseckeys/delete`.
+
+This is the standard method to be used by all read-only operations, and as such handlers for this method should generally be accessible to users with the "read-only" :term:`Role`.
+
+All endpoints dealing with the manipulation or fetching representations of "Traffic Control Objects" MUST support this method.
+
+POST
+----
+POST requests ask the server to process some provided data. Most commonly, in Traffic Ops, this means creating an object based on the serialization of said object contained in the request body, but it can also be used virtually whenever no other method is appropriate. When an object *is* created, the response body MUST contain a representation of the newly created object. POST requests do not need to be *idempotent*, unlike PUT requests.
+
+PUT
+---
+PUT is used to replace existing data with new data that is provided in the request body. :RFC:`2616#section-9.1.2` lists PUT as an "idempotent" request method, which means that subsequent identical requests should ensure the same state is maintained on the server. What this means is that a client that PUTs an object representation to Traffic Ops expects that if they then GET a representation of that object, do the same PUT again and GET another representation, the two retrieved representations should be identical. Effectively, the ``lastUpdated`` field that is common to objects in the :ref:`to-api` violates this, but the other properties of objects - which can actually be defined - generally obey this restriction. In general, fulfilling this restriction means that handlers will need to require the entirety of an object be defined in the request body.
+
+When an object is replaced, the response body MUST contain a representation of the object after replacement. While :RFC:`2616` states that servers MAY create objects for the passed representations if they do not already exist, :ref:`to-api` endpoint authors MUST instead use POST handlers for object creation.
+
+All endpoints that support the PUT request method MUST also support the :mailheader:`If-Unmodified-Since` HTTP header.

Review comment:
       nvm, I found it




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] mitchell852 commented on pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

mitchell852 commented on pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716#issuecomment-634272424


   @ocket8888 - want to link this to the contributing.md file?


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] mitchell852 merged pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

mitchell852 merged pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716


   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] ocket8888 commented on a change in pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

ocket8888 commented on a change in pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716#discussion_r430715956



##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.

Review comment:
       No, that's in the "Response" object section

##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.
+
+HTTP Request Methods
+====================
+:RFC:`7231#section-4` defines the semantics of HTTP/1.1 request methods. Authors should conform to that set of standards whenever possible, but for convenience the methods recognized by Traffic Ops and their meanings in that context are herein defined.
+
+GET
+---
+HTTP GET requests are issued by clients who want some data in response. In the context of Traffic Ops, this generally means a serialized representation of some object. GET requests MUST NOT alter the state of the server. An example of an API endpoint created in API version 1 that violates this restriction is :samp:`cdns/name/{name}/dnsseckeys/delete`.
+
+This is the standard method to be used by all read-only operations, and as such handlers for this method should generally be accessible to users with the "read-only" :term:`Role`.
+
+All endpoints dealing with the manipulation or fetching representations of "Traffic Control Objects" MUST support this method.
+
+POST
+----
+POST requests ask the server to process some provided data. Most commonly, in Traffic Ops, this means creating an object based on the serialization of said object contained in the request body, but it can also be used virtually whenever no other method is appropriate. When an object *is* created, the response body MUST contain a representation of the newly created object. POST requests do not need to be *idempotent*, unlike PUT requests.
+
+PUT
+---
+PUT is used to replace existing data with new data that is provided in the request body. :RFC:`2616#section-9.1.2` lists PUT as an "idempotent" request method, which means that subsequent identical requests should ensure the same state is maintained on the server. What this means is that a client that PUTs an object representation to Traffic Ops expects that if they then GET a representation of that object, do the same PUT again and GET another representation, the two retrieved representations should be identical. Effectively, the ``lastUpdated`` field that is common to objects in the :ref:`to-api` violates this, but the other properties of objects - which can actually be defined - generally obey this restriction. In general, fulfilling this restriction means that handlers will need to require the entirety of an object be defined in the request body.
+
+When an object is replaced, the response body MUST contain a representation of the object after replacement. While :RFC:`2616` states that servers MAY create objects for the passed representations if they do not already exist, :ref:`to-api` endpoint authors MUST instead use POST handlers for object creation.
+
+All endpoints that support the PUT request method MUST also support the :mailheader:`If-Unmodified-Since` HTTP header.

Review comment:
       Yes: [one of them is real, and the other isn't](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#Conditionals)
   
   I get that wrong all the time too. In fact, it was wrong in the original blueprint until Rob pointed it out.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [trafficcontrol] mitchell852 commented on a change in pull request #4716: API Guidelines

[GitBox <gi...@apache.org>]

mitchell852 commented on a change in pull request #4716:
URL: https://github.com/apache/trafficcontrol/pull/4716#discussion_r430709019



##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.
+
+HTTP Request Methods
+====================
+:RFC:`7231#section-4` defines the semantics of HTTP/1.1 request methods. Authors should conform to that set of standards whenever possible, but for convenience the methods recognized by Traffic Ops and their meanings in that context are herein defined.
+
+GET
+---
+HTTP GET requests are issued by clients who want some data in response. In the context of Traffic Ops, this generally means a serialized representation of some object. GET requests MUST NOT alter the state of the server. An example of an API endpoint created in API version 1 that violates this restriction is :samp:`cdns/name/{name}/dnsseckeys/delete`.
+
+This is the standard method to be used by all read-only operations, and as such handlers for this method should generally be accessible to users with the "read-only" :term:`Role`.
+
+All endpoints dealing with the manipulation or fetching representations of "Traffic Control Objects" MUST support this method.
+
+POST
+----
+POST requests ask the server to process some provided data. Most commonly, in Traffic Ops, this means creating an object based on the serialization of said object contained in the request body, but it can also be used virtually whenever no other method is appropriate. When an object *is* created, the response body MUST contain a representation of the newly created object. POST requests do not need to be *idempotent*, unlike PUT requests.
+
+PUT
+---
+PUT is used to replace existing data with new data that is provided in the request body. :RFC:`2616#section-9.1.2` lists PUT as an "idempotent" request method, which means that subsequent identical requests should ensure the same state is maintained on the server. What this means is that a client that PUTs an object representation to Traffic Ops expects that if they then GET a representation of that object, do the same PUT again and GET another representation, the two retrieved representations should be identical. Effectively, the ``lastUpdated`` field that is common to objects in the :ref:`to-api` violates this, but the other properties of objects - which can actually be defined - generally obey this restriction. In general, fulfilling this restriction means that handlers will need to require the entirety of an object be defined in the request body.
+
+When an object is replaced, the response body MUST contain a representation of the object after replacement. While :RFC:`2616` states that servers MAY create objects for the passed representations if they do not already exist, :ref:`to-api` endpoint authors MUST instead use POST handlers for object creation.
+
+All endpoints that support the PUT request method MUST also support the :mailheader:`If-Unmodified-Since` HTTP header.

Review comment:
       different than `If-Not-Modified-Since`?

##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.

Review comment:
       did u want to mention min, max, mean here?

##########
File path: docs/source/development/api_guidelines.rst
##########
@@ -0,0 +1,268 @@
+..
+..
+.. 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.
+..
+
+.. _api-guidelines:
+
+**************
+API Guidelines
+**************
+This section lays out guidelines to be considered by API endpoint authors. What follows are not *strictly* hard-and-fast rules, but there should be a very convincing argument accompanying endpoints that do not follow them.
+
+Legacy API versions don't, in general, adhere to these principles. This section is not meant as a proposal for altering them to be compliant, but merely a set of guidelines for future work.
+
+Response Bodies
+===============
+All valid API responses will be in the form of some serialized object. The main data that represents the result of the client's request MUST appear in the ``response`` property of that object. If a warning, error message, success message, or informational message is to be issued by the server, then they MUST appear in the ``alerts`` property of the response. Some endpoints may return ancillary statistics such as the total number of objects when pagination occurs, which should be placed in the ``summary`` property of the response.
+
+Response
+--------
+The ``response`` property of a serialized response object MUST only contain object representations as requested by the client. In particular, it MUST NOT contain admonitions, success messages, informative messages, or statistic summaries beyond the scope requested by the client.
+
+Equally unacceptable API responses are shown in :ref:`success-as-response` and :ref:`extra-field`.
+
+.. _success-as-response:
+.. code-block:: json
+	:caption: Success Message as Response Object
+
+	{
+		"response": "Thing was successfully created."
+	}
+
+.. _extra-field:
+.. code-block:: json
+	:caption: Illegal Top-Level Property
+
+	{
+		"response": {"foo": "bar"},
+		"someOtherField": {"someOtherObject"}
+	}
+
+When requests are serviced by Traffic Ops that pass data asking that the returned object list be filtered, the response property MUST be a filtered array of those objects (assuming the request may be successfully serviced). This is true even if filtering is being done according to a uniquely identifying property - e.g. a numeric ID. The ``response`` field of an object returned in response to a request to create, update, or delete one or more resources may be either a single object representation or an array thereof according to the number of objects created, updated, or deleted. However, if a handler is *capable* of creating, updating, or deleting more than one object at a time, the ``response`` field SHOULD consistently be represented as an array - even if its length would only be 1.
+
+The proper value of an empty collection is an empty collection. If a Foo can have zero or more Bars, then the representation of a Foo with no Bars MUST be an empty array/list/set, and in particular MUST NOT be either missing from the representation or represented as the "Null" value of the representation format. That is, if Foos have no other property than their Bars, then a Foo with no Bars may be represented in JSON encoding as ``{"bars":[]}``, but not as ``{"bars":null}`` or ``{}``. Similarly, an empty string field is properly represented as an empty string - e.g. ``{"bar":""}`` not ``{"bar":null}`` or ``{}`` - and the "zero-value" of numbers is zero itself - e.g. ``{"bar":0}`` not ``{"bar":null}`` or ``{}``. Note that "null" values *are allowed* when appropriate, but "null" values represent the *absence* of a value rather than the "zero-value" of a property. If a property is *missing* from an object representation it indicates the absence of that property, and because of that there must be a *very convincing* argument if and when that is the case.
+
+As a special case, endpoints that report statistics including minimums, maximums and arithmetic means of data sets MUST use the property names ``min``, ``max``, and ``mean``, respectively, to express those concepts. These SHOULD be properties of ``response`` directly whenever that makes sense.
+
+Alerts
+------
+Alerts should be presented as an array containing objects which each conform to the object definition laid out by :atc-godoc:`the ATC library's Alert structure <lib/go-tc#Alert>`. The allowable ``level``\ s of an Alert are:
+
+- ``error`` - This level MUST be used to indicate conditions that caused a request to fail. Because of this, this level MUST NOT appear in the ``alerts`` array of responses with any HTTP response code less than 400 (except when used for asynchronous tasks as discussed in `202 Accepted`_). Details of server workings and/or failing components MUST NOT be exposed in this message, which should otherwise be as descriptive as possible.
+- ``info`` - This level SHOULD be used to convey supplementary information to a user that is not directly the result of their request. This SHOULD NOT carry information indicating whether or not the request succeeded and why/why not, as that is best left to the ``error`` and ``success`` levels.
+- ``success`` - This level MUST be used to convey success messages to the client. In general, it is expected that the message will be directly displayed to the user by the client, and therefore can be used to add human-friendly details about a request beyond the response payload. This level MUST NOT appear in the ``alerts`` array of responses with an HTTP response code that is not between 200 and 399 (inclusive).
+- ``warning`` - This level is used to warn clients of potentially dangerous conditions when said conditions have not caused a request to fail. The best example of this is deprecation warnings, which should appear on all API routes that have been deprecated.
+
+Summary
+-------
+The ``summary`` object is used to provide summary statistics about object collections. In general the use of ``summary`` is left to be defined by API endpoints (subject to some restrictions). However, its use is not appropriate in cases where the user is specifically requesting summary statistics, but should rather be used to provide supporting information - pre-calculated - about a set of objects or data that the client *has* requested.
+
+Endpoints MUST use the following, reserved properties of ``summary`` for their described purposes (when use of ``summary`` is appropriate) rather than defining new ``summary`` or ``response`` properties to suit the same purpose:
+
+- ``count`` - Count contains an unsigned integer that defines the total number of results that could possibly be returned given the non-pagination query parameters supplied by the client.
+
+HTTP Request Methods
+====================
+:RFC:`7231#section-4` defines the semantics of HTTP/1.1 request methods. Authors should conform to that set of standards whenever possible, but for convenience the methods recognized by Traffic Ops and their meanings in that context are herein defined.
+
+GET
+---
+HTTP GET requests are issued by clients who want some data in response. In the context of Traffic Ops, this generally means a serialized representation of some object. GET requests MUST NOT alter the state of the server. An example of an API endpoint created in API version 1 that violates this restriction is :samp:`cdns/name/{name}/dnsseckeys/delete`.
+
+This is the standard method to be used by all read-only operations, and as such handlers for this method should generally be accessible to users with the "read-only" :term:`Role`.
+
+All endpoints dealing with the manipulation or fetching representations of "Traffic Control Objects" MUST support this method.
+
+POST
+----
+POST requests ask the server to process some provided data. Most commonly, in Traffic Ops, this means creating an object based on the serialization of said object contained in the request body, but it can also be used virtually whenever no other method is appropriate. When an object *is* created, the response body MUST contain a representation of the newly created object. POST requests do not need to be *idempotent*, unlike PUT requests.
+
+PUT
+---
+PUT is used to replace existing data with new data that is provided in the request body. :RFC:`2616#section-9.1.2` lists PUT as an "idempotent" request method, which means that subsequent identical requests should ensure the same state is maintained on the server. What this means is that a client that PUTs an object representation to Traffic Ops expects that if they then GET a representation of that object, do the same PUT again and GET another representation, the two retrieved representations should be identical. Effectively, the ``lastUpdated`` field that is common to objects in the :ref:`to-api` violates this, but the other properties of objects - which can actually be defined - generally obey this restriction. In general, fulfilling this restriction means that handlers will need to require the entirety of an object be defined in the request body.
+
+When an object is replaced, the response body MUST contain a representation of the object after replacement. While :RFC:`2616` states that servers MAY create objects for the passed representations if they do not already exist, :ref:`to-api` endpoint authors MUST instead use POST handlers for object creation.
+
+All endpoints that support the PUT request method MUST also support the :mailheader:`If-Unmodified-Since` HTTP header.
+
+PATCH
+-----
+At the time of this writing, no :ref:`to-api` endpoints handle the PATCH request method. PATCH requests that the server's stored data be mutated in some way using data provided in the request body. Unlike PUT, PATCH is not *idempotent*, which essentially means that it can be used to change only part of a stored object. When an object is modified, the response body MUST contain a representation of the object after modification, and that representation SHOULD fully describe the modified object, even the parts that were not modified.
+
+Handlers that implement PATCH in the :ref:`to-api` MUST use conditional requests to ensure that race conditions are not a problem, specifically they MUST support using :mailheader:`ETag` and :mailheader:`If-Match`, and SHOULD also support :mailheader:`If-Not-Modified-Since`.
+
+Clients SHOULD use PATCH requests rather than PUT requests for modifying existing resources whenever it is supported.
+
+DELETE
+------
+DELETE destroys an object stored on the server. Typically the request will contain identifying information for the object(s) to be destroyed either in the request URI or in the request's body. :ref:`to-api` endpoint authors MUST use this request method whenever an object identified by the request URI is being destroyed. When such deletion successfully occurs, the response body MUST contain a representation of the destroyed object.
+
+HTTP Response Codes
+===================
+Proper use of HTTP response codes can significantly improve user interfaces built on top of the API. What follows is a (non-exhaustive) set of response codes and their appropriate use in the context of Traffic Ops. For more complete information, refer to `the Mozilla Developer Network's HTTP Response Code list <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status>`_.
+
+200 OK
+------
+This indicates the request succeeded, with no additional semantics. This MUST be the exact response status code of successful GET requests. This is also the default "success" response code for any other request.
+
+201 Created
+-----------
+This indicates that a resource was successfully created on the server. This MUST be the response status code of POST requests that create a new object or objects on the server, and in that case the response SHOULD also include a :mailheader:`Location` header that provides a URI where a representation of the newly created object may be requested.
+
+202 Accepted
+------------
+``202 Accepted`` MUST be used when the server is performing some task asynchronously (e.g. refreshing DNSSEC keys) but the status of that task cannot be ascertained at the current time. Ideally in this case, when the task completes - either successfully or by failing - the Traffic Ops changelog will be updated to indicate that status, along with information to uniquely identify the task (e.g. username and date/time when the task started).
+
+Endpoints that create asynchronous jobs SHOULD provide a URI to which the client may send GET requests to obtain a representation of the job's current state in the :mailheader:`Location` HTTP header. They MAY also provide an ``info``-level Alert that provides the same or similar information in a more human-friendly manner.
+
+The responses to such GET requests are subject to the same restrictions as any other API endpoint, but have the added restriction that the ``response`` objects sent MUST have the ``status`` property, which is a string limited to one of the following values and having the associated semantics:
+
+PENDING
+	This means the job has been started but is not yet completed.
+SUCCEEDED
+	This means that the asynchronous job has completed and encountered no errors.
+FAILED
+	The task encountered errors and was unable to continue, and thus has been terminated.
+
+Note that the response code of the response carrying this information MUST NOT depend on the value of ``status``. In particular, a response that successfully reports the status of a FAILED asynchronous task is still successfully servicing a client's GET request, and therefore MUST have the ``200 OK`` response status code. However, a response encoding a FAILED ``status`` MUST be accompanied by one or more ``error``-level Alerts that explain (to the greatest degree of detail allowable securely) why the job failed.
+
+These responses MUST also include the ``startTime`` and ``endTime`` properties which indicate, respectively, the time at which the asynchronous job started and the time at which it concluded. A job that has not started MUST have a Null-valued ``startTime`` and likewise a job that has yet to conclude MUST have a Null-value ``endTime``.
+
+400 Bad Request
+---------------
+In general this is used when there's something syntactically wrong with the client's request. For example, Traffic Ops MUST respond with this code when the request body was improperly encoded. In most cases, this is also the proper response code when the client submits data that is not semantically correct. For example, dates/times represented as timestamp strings in an unsupported format should trigger this response code.
+
+This is also the default "client failure" response code for any other request.
+
+The response body MUST include an entry in the ``alerts`` array that describes to the client what was wrong with the request.
+
+401 Unauthorized
+----------------
+This MUST be the response code when a client without valid authorization information in the HTTP headers requests a resource which cannot be accessed without first authorizing. Which should be everything except ``/ping`` and endpoints that provide authorization.
+
+403 Forbidden
+-------------
+This MUST be used whenever the client is logged-in, but still does not have access to the resource they are requesting. It MUST also be used when they have some access to the resource, but not with the specific request method they used. This can pertain to restricted access on the basis of :term:`Role`, User Permissions, as well as :term:`Tenancy`.
+
+The response body MUST NOT disclose any information regarding why the user was denied access.
+
+404 Not Found
+-------------
+This MUST be the returned status code when the client requests a path that does not exist on the server. Note that a *path* does not include a *query string*; in the URL ``http://example.test/some/path?query#frag`` the *path* consists of only ``/some/path``.
+
+409 Conflict
+------------
+This SHOULD be used when the request cannot be completed because the current state of the server is fundamentally incompatible with the request. For example, creating a new user with an email that is already in use should result in this response.
+
+Additionally, this MAY be used instead of `404 Not Found`_ when the client is requesting a link between an object identified by the request URI and some other object (e.g. when assigning a :term:`cache server` to a :term:`Delivery Service`) when the other object does not exist. If the request URI identifies an object that does not exist, the response MUST use `404 Not Found`_ instead.
+
+This is also the proper response status code when the conditions of a request cannot be met, e.g. when a client submits a PATCH request for a resource with an :mailheader:`If-Match` header that does not match the stored object's :mailheader:`ETag`.
+
+The request body MUST indicate what the conflict is that prevented the request from being fulfilled via one or more ``error``-level alerts.

Review comment:
       response body?




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org