diff --git a/api/openapi.yaml b/api/openapi.yaml index b319054..42591e3 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -34,12 +34,13 @@ paths: '400': $ref: '#/components/responses/ErrorResponse' - /list_locations: + /locations: get: + description: Lists all the visible locations to the caller. parameters: - name: asn in: query - description: List avaible locations for peering with the given ASN + description: List available locations for peering with the given ASN required: true schema: type: integer @@ -50,22 +51,36 @@ paths: required: false schema: $ref: '#/components/schemas/LocationType' + - name: max_results + in: query + description: Hint to paginate the request with the maximum number of results the caller is able to process. + required: false + schema: + type: integer + default: 0 + minimum: 0 + maximum: 100 + - name: next_token + in: query + description: Indication of the offset to retrieve the next page on a previously initiated paginated request. + required: false + schema: + type: string responses: '200': description: OK content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/Location' - + $ref: '#/components/responses/ListLocationsResponse' '400': $ref: '#/components/responses/ErrorResponse' + '403': + $ref: '#/components/responses/ErrorResponse' - /add_sessions: + /sessions: post: - description: Request peering + description: Requests a new set of sessions to be created. requestBody: description: Request to create peering sessions content: @@ -79,18 +94,14 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/SessionArray' - '300': - description: Request modified or partially accepted - content: - application/json: - schema: - $ref: '#/components/schemas/SessionArray' + $ref: '#/components/responses/CreateSessionsResponse' '400': $ref: '#/components/responses/ErrorResponse' + '403': + $ref: '#/components/responses/ErrorResponse' - /get_status: get: + description: Lists a set of sessions visible to the caller. Each session in the set contains a summary of its current status. parameters: - name: asn in: query @@ -98,10 +109,62 @@ paths: required: true schema: type: integer - - name: request_id + - name: max_results in: query - description: request identifier + description: Hint to paginate the request with the maximum number of results the caller is able to process. required: false + schema: + type: integer + default: 0 + minimum: 0 + maximum: 100 + - name: next_token + in: query + description: Indication of the offset to retrieve the next page on a previously initiated paginated request. + required: false + schema: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/responses/ListSessionsResponse' + '400': + $ref: '#/components/responses/ErrorResponse' + '403': + $ref: '#/components/responses/ErrorResponse' + + delete: + description: Requests to turn the session down and delete it from the server. + requestBody: + description: Request to delete peering sessions + content: + application/json: + schema: + $ref: '#/components/schemas/SessionReferenceArray' + required: true + responses: + '200': + description: Sessions are scheduled for deletion and no longer usable + content: + application/json: + schema: + $ref: '#/components/responses/DeleteSessionsResponse' + '400': + $ref: '#/components/responses/ErrorResponse' + '403': + $ref: '#/components/responses/ErrorResponse' + + /sessions/{session_id}: + get: + description: Retrieves a given session by it server-generated ID provided on creation. + parameters: + - name: session_id + in: path + description: Server-generated stable identifier for the session. + required: true schema: type: string responses: @@ -110,9 +173,37 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/SessionArray' + $ref: '#/components/schemas/Session' '400': $ref: '#/components/responses/ErrorResponse' + '403': + $ref: '#/components/responses/ErrorResponse' + '404': + $ref: '#/components/responses/ErrorResponse' + + delete: + description: Requests to turn the session down and delete it from the server. + parameters: + parameters: + - name: session_id + in: path + description: Server-generated stable identifier for the session. + required: true + schema: + type: string + responses: + '200': + description: Session is scheduled for deletion and no longer usable + content: + application/json: + schema: + $ref: '#/components/schemas/Session' + '400': + $ref: '#/components/responses/ErrorResponse' + '403': + $ref: '#/components/responses/ErrorResponse' + '404': + $ref: '#/components/responses/ErrorResponse' components: schemas: @@ -138,6 +229,40 @@ components: Add choices type: string + LocationArray: + title: Locations + description: Array of peering locations + type: array + items: + $ref: '#/components/schemas/Location' + + SessionRequestArray: + title: BGP Sessions requested + description: Array of BGP Sessions requested + type: array + items: + $ref: '#/components/schemas/SessionRequestItem' + + SessionRequestItem: + title: BGP Session Request + description: BGP Session Request + type: object + properties: + local_asn: + type: integer + local_ip: + type: string + peer_asn: + type: integer + peer_ip: + type: string + peer_type: + type: string + md5: # TODO or auth: md5: $key? + type: string + location: + $ref: '#/components/schemas/Location' + SessionArray: title: BGP Sessions description: Array of BGP Sessions @@ -166,11 +291,30 @@ components: $ref: '#/components/schemas/Location' status: $ref: '#/components/schemas/SessionStatus' - uuid: + session_id: type: string description: |- unique identifier (also serves as request id) Could separate into local_ and peer_? + + SessionReferenceArray: + title: BGP Session References + description: Array of BGP Session References + type: array + sessions: + $ref: '#/components/schemas/SessionReference' + + SessionReference: + title: BGP Session Reference + description: Reference to univocally identify a BGP Session + type: object + properties: + session_id: + type: string + description: |- + unique identifier (also serves as request id) + Could separate into local_ and peer_? + Error: title: Error type: object @@ -206,7 +350,56 @@ components: - name - errors + requests: + CreateSessionsRequest: + title: CreateSessionsRequest + description: Response to a request to create sessions + type: object + properties: + sessions: + $ref: '#/components/schemas/SessionRequestArray' + responses: + ListLocationsResponse: + title: ListLocationsResponse + description: Response to a list for locations + type: object + properties: + next_token: + type: string + locations: + $ref: '#/components/schemas/LocationArray' + + CreateSessionsResponse: + title: CreateSessionsResponse + description: Response to a request to create sessions + type: object + properties: + sessions: + $ref: '#/components/schemas/SessionArray' + errors: + $ref: '#/components/schemas/Error' + + ListSessionsResponse: + title: ListSessionsResponse + description: Response to a list for sessions + type: object + properties: + next_token: + type: string + sessions: + $ref: '#/components/schemas/SessionArray' + + DeleteSessionsResponse: + title: DeleteSessionsResponse + description: Response to a request to delete sessions + type: object + properties: + sessions: + $ref: '#/components/schemas/SessionArray' + errors: + $ref: '#/components/schemas/Error' + ErrorResponse: description: API Error response content: