From 5d95efc54f94daa1b2776059765dd80041703d0d Mon Sep 17 00:00:00 2001 From: Carlos Aguado Date: Fri, 8 Mar 2024 19:18:27 +0000 Subject: [PATCH] Cleanup references to agreed changes in API This commit cleans up the references to the item_id and clarifies the HTTP return code for partial results. --- draft-ramseyer-grow-peering-api.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/draft-ramseyer-grow-peering-api.md b/draft-ramseyer-grow-peering-api.md index 6a37078..9b6d88d 100644 --- a/draft-ramseyer-grow-peering-api.md +++ b/draft-ramseyer-grow-peering-api.md @@ -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. @@ -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. @@ -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 @@ -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. * 400: * Error * 403: @@ -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: @@ -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: @@ -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.