Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleanup references to agreed changes in API #23

Merged
merged 1 commit into from
Mar 13, 2024
Merged

Cleanup references to agreed changes in API #23

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions draft-ramseyer-grow-peering-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,6 @@ REQUEST {#request}
5. Peer Type (public or private)
6. MD5 (optional with encoding agreed outside of this specification)
7. Location (Commonly agreed identifier of the BGP speaker, e.g. PeeringDB IX lan ID)
8. Item ID (identifies the session within the set requested)

* The receiver's expected actions:
* The server confirms requested clientASN in list of authorized ASNs.
Expand All @@ -234,7 +233,7 @@ REQUEST {#request}
* APPROVAL CASE
* Server returns a list with the structure for each of the acceptable peering sessions. Note: this structure may also contain additional attributes such as the server generated session ID.
* PARTIAL APPROVAL CASE
* Server returns a list with the structure for each of the acceptable peering sessions as in the approval case. The server also returns a list of sessions that have not deemed as validated or acceptable to be created. The set of sessions accepted and rejected is disjoint and the join of both sets matches the cardinality of the requested sessions. The sessions on each set are associated to the client request by the Item ID specified for each session.
* Server returns a list with the structure for each of the acceptable peering sessions as in the approval case. The server also returns a list of sessions that have not deemed as validated or acceptable to be created. The set of sessions accepted and rejected is disjoint and the join of both sets matches the cardinality of the requested sessions.
* REJECTION CASE
* Server returns an error message which indicates that all of the sessions requested have been rejected and the reason for it.

Expand Down Expand Up @@ -319,7 +318,7 @@ BGP Session
* md5 (optional, as defined above)
* location (Peering Location, as defined above)
* status (Session Status, as defined above)
* session_id (of individual session generated by the server. Client provides a item ID to track the session within the request, but the server's session ID will be the final definitive ID)
* session_id (of individual session and generated by the server)

Error

Expand All @@ -342,9 +341,7 @@ On each call, there should be rate limits, allowed senders, and other optional r
* Request body: Session Array
* Responses:
* 200 OK:
* Contents: Session Array (all sessions in request accepted for configuration).
* 300:
* Contents: Modified Session Array, with rejected or additional sessions.
* Contents: Session Array (all sessions in request accepted for configuration). Should not all the sessions be accepted, the response also contains a list of sessions and the respective errors.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(not blocking the merge) Is this a separate list, or will the rejected sessions be listed with status: "rejected"?
The second case makes sense to me, just confirming we are in alignment.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The response contains 2 lists, the list of sessions and a list of errors. Either can be full-empty, partial-partial, empty-full to signify what happened to the collection of requested resources. The sum of both should match that of the request.

The error code was under question and I haven't found a conclusive source on what 2xx matches a partial accepted request (206 implies content ranges and 207 caldav) so opted to not overload existing 2xx with additional semantics. In the same way we expect initiators to match by some property each item of the response to each item of the request, the absence of one successful can be matched against the errors in the error list.

* 400:
* Error
* 403:
Expand All @@ -359,11 +356,11 @@ On each call, there should be rate limits, allowed senders, and other optional r
* asn (requesting client's asn)
* request_id (optional, UUID of request)
* max_results (integer to indicate an upper bound for a given response page)
* next_token (opaque string to hint the query and last result returned when fetching a new page)
* next_token (opaque and optional string received on a previous response page and which allows the server to produce the next page of results. Its absence indicates to the server that the first page is expected)
* Response:
* 200: OK
* Contents: Session Array of sessions in request_id, if provided. Else, all existing and in-progress sessions between client ASN and server.
* next_token (opaque string for clients to use when retrieving a new page)
* next_token (opaque and optional string the server expects to be passed back on the request for the next page. Its absence indicates to the client that no more pages are available)
* 400:
* Error (example: request_id is invalid)
* 403:
Expand Down Expand Up @@ -412,11 +409,11 @@ Endpoints which provide useful information for potential interconnections.
* asn (Server ASN, with which to list potential connections)
* location_type (Optional: Peering Location)
* max_results (integer to indicate an upper bound for a given response page)
* next_token (opaque string to hint the query and last result returned when fetching a new page)
* next_token (opaque and optional string received on a previous response page and which allows the server to produce the next page of results. Its absence indicates to the server that the first page is expected)
* Response:
* 200: OK
* Contents: List of Peering Locations.
* next_token (opaque string for clients to use when retrieving a new page)
* next_token (opaque and optional string the server expects to be passed back on the request for the next page. Its absence indicates to the client that no more pages are available)
* 400:
* Error
* 403:
Expand All @@ -439,8 +436,6 @@ Endpoints which provide useful information for potential interconnections.
* LAG struct, with server data populated
* LOA or way to receive it
* Request ID
* 300:
* Proposed Modification: LAG struct, LOA, email address for further discussion
* 40x: rejections
* REMOVE PNI
* As ADD/AUGMENT in parameters. Responses will include a requestID and status.
Expand Down
Loading