[GitHub] [trafficcontrol] rob05c commented on a change in pull request #4536: API Guidelines blueprint

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

rob05c commented on a change in pull request #4536: API Guidelines blueprint
URL: https://github.com/apache/trafficcontrol/pull/4536#discussion_r404261930
 
 

 ##########
 File path: blueprints/api.guidelines.md
 ##########
 @@ -0,0 +1,549 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you 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
+
+## Problem Description
+The Traffic Ops API duplicates a lot of functionality, is at times
+self-inconsistent, and can be difficult to work with.
+
+## Proposed Changes
+Many manifestations of the above problems could be avoided entirely by adhering
+to a set of guidelines for how our API ought to behave. That would certainly
+make it more consistent, and would make the intended behavior much easier to
+discern. Herein lie a proposed set of API guidelines that have been discussed
+by the Traffic Ops working group over the past few months.
+
+These rules aren't meant to necessarily be ironclad, but there should be a very
+convincing argument accompanying endpoints that do not follow them.
+
+### 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 below.
+
+```json
+{
+	"response": "Thing was successfully created."
+}
+```
+
+```json
+{
+	"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
+[the ATC library's Alert structure](https://godoc.org/github.com/apache/trafficcontrol/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. 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 th
+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 2616 Section 9](https://tools.ietf.org/html/rfc2616#section-9) defines the
 
 Review comment:
   RFC 2616 is obsolete, should be RFC 7231 Section 4: https://tools.ietf.org/html/rfc7231#section-4

----------------------------------------------------------------
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


With regards,
Apache Git Services