Update draft-ramseyer-grow-peering-api.md

draft-ramseyer-grow-peering-api.md

@@ -54,7 +54,7 @@ By using the Peering API, entities requesting and accepting peering can signific
 
 * Reducing in person-hours spent configuring peering
 * Reducing configuration mistakes by reducing human interaction
-* And by peering, reducing network latency through expansion of interconneciton relationships
+* And by peering, reducing network latency through expansion of interconnection relationships
 
 
 
@@ -66,36 +66,26 @@ All terms used in this document will be defined here:
 * Receiver: Network that is receiving communications about peering
 * Configured: peering session that is set up on one side
 * Established: session is already defined as per BGP4 specification (page 71)
+* Public Peering: Settlement-free peering
+* Session: A BGP Session
+* ASN: Autonomous System Number
 
 
 
 # Security Considerations
-
-PeeringDB OAuth will be the minimum requirement for authorization of API requests.
+As peering connections exchange real internet traffic, this API requires a security component to verify that the requestor is allowed to request peering on behalf of that ASN.
+In the initial proposal, this API intended to require PeeringDB-based authentication as the standard.
+After further discussion, it was decided to offer different authentication options, to accomodate the security concerns of different parties.
+There are several possible extensions to the authentication model, including RPKI-based authentication, and additional OAuth providers.
+For RPKI-based authentication, this document refers to RFC9323.
+However, this document hopes that, through the RFC process, the Working Group can come to a consensus on a base "authentication standard," to ease adoption for peering partners.
 
 # Protocol
-(Jenny--this is not up-to-date, but I pasted in what we had in the google doc and will revise)
-TODO: Update this spec, include API endpoints
-
-## full list of endpoints:
-* ADD IX PEER
-* Augment IX PEER
-* TOPUP IX
-* NEW IX
-* REMOVE IX PEER
-* ADD PNI
-* AUGMENT PNI
-* REMOVE PNI
-* STATUS of PNI/IX CONNECTIONS
-* MAINTENANCE (notification) (no tickets)
-* ADD ROUTE SERVER
-* DELETE RS
-* QUERY for request status
-* On each call, there should be:
-  * Rate limits, allowed senders, and other restriction options
-  * Request source
+The Peering API follows the RESTful API model, implementing different endpoints for desired configuration actions.
+See "Endpoints" for the complete list.
+The Peering API provides a full flow for discovering, configuring, and removing, BGP connections.
 
-## Request flow
+## Request Flow
 1. AUTH phase: initiator makes an authenticated request to receiver via PeeringDB OAUTH.  This provides the receiver with initiator’s credentials to verify who they say they are
 2. REQUEST phase:
     1. ADD: What is the initial information provided
@@ -142,6 +132,23 @@ TODO: Update this spec, include API endpoints
         2. Initiator closes connection with a GOODBYE.  Any subsequent followups must start this process over again.  If the receiver has responded with a GOODBYE, then any subsequent monitoring calls will receive a GOODBYE.  If a GOODBYE was presented erroneously, the initiator can make a new request asking the receiver to delete the session and retry.
     4. Else, wait TimeWindow and retry
     5. If initiator does not make a request in 3*TimeWindow or 1 week (whichever is longer), receiver automatically sends a GOODBYE and deletes the sessions on their side.
+## ENDPOINTS:
+* ADD IX PEER
+* Augment IX PEER
+* TOPUP IX
+* NEW IX
+* REMOVE IX PEER
+* ADD PNI
+* AUGMENT PNI
+* REMOVE PNI
+* STATUS of PNI/IX CONNECTIONS
+* MAINTENANCE (notification) (no tickets)
+* ADD ROUTE SERVER
+* DELETE RS
+* QUERY for request status
+* On each call, there should be:
+  * Rate limits, allowed senders, and other restriction options
+  * Request source
 
 # API Endpoints and Specifications
 TODO: list endpoints, both v0 and vLater