Federation api endpoints with OpenAPI Schema version 3
Issue #1414
resolved
Following https://bitbucket.org/openid/connect/pull-requests/108 we have a useful division of endpoints by scopes.
Would you like to have an appendix with a OAS3 schema describing these endpoints?
Comments (6)
-
reporter
-
reporter
-
reporter
Here an example of OAS3 for OIDC Federation 1.0
{ "openapi":"3.0.0", "info":{ "title":"SPID/CIE OIDC OpenAPI 3.0 Documentation", "description":"OpenAPI 3.0 Document Description", "termsOfService":"", "contact":{ "email":"contatti@developers.italia.it", "url":"https://github.com/italia/spid-cie-oidc-django", "name":"Developers Italia" }, "license":{ "name":"CC BY 4.0", "url":"https://creativecommons.org/licenses/by/4.0/" }, "version":"0.5.1", "x_logo":{ "name":"Developers italia", "url":"https://developers.italia.it/assets/icons/logo-it.svg" } }, "servers":[ ], "paths":{ "/fetch/":{ "get":{ "tags":[ "Federation API" ], "summary":"fetch", "description":"All entities that are expected to publish entity statements about other entities MUST expose a Fetch endpoint.\nFetching entity statements is performed to collect entity statements one by one to gather trust chains.\nTo fetch an entity statement, an entity needs to know the identifier of the entity to ask (the issuer), the fetch endpoint of that entity and the identifier of the entity that you want the statement to be about (the subject).", "parameters":[ ], "requestBody":{ "description":"", "content":{ "application/x-www-form-urlencoded":{ "schema":{ "title":"FetchRequest", "type":"object", "properties":{ "sub":{ "title":"Sub", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "iss":{ "title":"Iss", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "aud":{ "title":"Aud", "type":"array", "items":{ "type":"string", "minLength":1, "maxLength":2083, "format":"uri" } } }, "required":[ "sub" ] } } }, "required":false }, "responses":{ "400":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "404":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "200":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FetchResponse", "type":"object", "properties":{ "jose":{ "title":"Jose", "pattern":"^[a-zA-Z\\_\\-0-9]+\\.[a-zA-Z\\_\\-0-9]+\\.[a-zA-Z\\_\\-0-9]+", "type":"string" } }, "required":[ "jose" ] } } } } } }, "parameters":[ ] }, "/list/":{ "get":{ "tags":[ "Federation API" ], "summary":"entity_list", "description":"", "parameters":[ ], "requestBody":{ "description":"", "content":{ "application/x-www-form-urlencoded":{ "schema":{ "title":"ListRequest", "type":"object", "properties":{ "is_leaf":{ "title":"Is Leaf", "type":"boolean" }, "type":{ "title":"Type", "enum":[ "openid_relying_party", "openid_provider", "oauth_resource", "federation_entity" ], "type":"string" } } } } }, "required":false }, "responses":{ "400":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "404":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "200":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"ListResponse", "type":"object", "properties":{ "response":{ "title":"Response", "type":"array", "items":{ "type":"string", "minLength":1, "maxLength":2083, "format":"uri" } } }, "required":[ "response" ] } } } } } }, "parameters":[ ] }, "/resolve/":{ "get":{ "tags":[ "Federation API" ], "summary":"resolve_entity_statement", "description":"Resolves the final metadata of its descendants. In this implementation we only returns a preexisting Metadata.", "parameters":[ ], "requestBody":{ "description":"", "content":{ "application/x-www-form-urlencoded":{ "schema":{ "title":"ResolveRequest", "type":"object", "properties":{ "sub":{ "title":"Sub", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "anchor":{ "title":"Anchor", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "iss":{ "title":"Iss", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "format":{ "title":"Format", "enum":[ "json" ], "type":"string" } }, "required":[ "sub", "anchor", "format" ] } } }, "required":false }, "responses":{ "400":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "404":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "200":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"ResolveResponse", "type":"object", "properties":{ "iss":{ "title":"Iss", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "sub":{ "title":"Sub", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "iat":{ "title":"Iat", "type":"integer" }, "exp":{ "title":"Exp", "type":"integer" }, "trust_marks":{ "title":"Trust Marks", "type":"string", "format":"json-string" }, "metadata":{ "title":"Metadata", "type":"string", "format":"json-string" } }, "required":[ "iss", "sub", "iat", "exp" ] } } } } } }, "parameters":[ ] }, "/trust_mark_status/":{ "get":{ "tags":[ "Federation API" ], "summary":"trust_mark_status", "description":"", "parameters":[ ], "requestBody":{ "description":"", "content":{ "application/x-www-form-urlencoded":{ "schema":{ "title":"TrustMarkRequest", "type":"object", "properties":{ "sub":{ "title":"Sub", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "id":{ "title":"Id", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "trust_mark":{ "title":"Trust Mark", "pattern":"^[a-zA-Z\\_\\-0-9]+\\.[a-zA-Z\\_\\-0-9]+\\.[a-zA-Z\\_\\-0-9]+", "type":"string" } }, "required":[ "trust_mark" ] } } }, "required":false }, "responses":{ "400":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "404":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "200":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"TrustMarkResponse", "type":"object", "properties":{ "active":{ "title":"Active", "type":"boolean" } }, "required":[ "active" ] } } } } } }, "parameters":[ ] }, "/advanced_entity_listing/":{ "get":{ "tags":[ "Federation API" ], "summary":"advanced_entity_listing", "description":"", "parameters":[ ], "requestBody":{ "description":"", "content":{ "application/x-www-form-urlencoded":{ "schema":{ "title":"AdvancedEntityListRequest", "type":"object", "properties":{ "page":{ "title":"Page", "type":"integer" } } } } }, "required":false }, "responses":{ "400":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "404":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"FedAPIErrorResponse", "type":"object", "properties":{ "operation":{ "title":"Operation", "type":"string" }, "error":{ "title":"Error", "enum":[ "invalid_request" ], "type":"string" }, "error_description":{ "title":"Error Description", "type":"string" } }, "required":[ "error", "error_description" ] } } } }, "200":{ "description":"", "content":{ "application/json":{ "schema":{ "title":"AdvancedEntityListResponse", "type":"object", "properties":{ "iss":{ "title":"Iss", "minLength":1, "maxLength":2083, "format":"uri", "type":"string" }, "iat":{ "title":"Iat", "type":"integer" }, "entities":{ "title":"Entities", "type":"array", "items":{ "type":"string", "format":"json-string" } }, "page":{ "title":"Page", "type":"integer" }, "total_pages":{ "title":"Total Pages", "type":"integer" }, "total_entries":{ "title":"Total Entries", "type":"integer" }, "next_page_path":{ "title":"Next Page Path", "type":"string" }, "prev_page_path":{ "title":"Prev Page Path", "type":"string" } }, "required":[ "iss", "iat", "entities", "page", "total_pages", "total_entries", "next_page_path", "prev_page_path" ] } } } } } }, "parameters":[] } }, "components":{ "schemas":{}, "responses":{}, "parameters":{}, "examples":{}, "requestBodies":{}, "headers":{}, "securitySchemes":{}, "links":{}, "callbacks":{}, }, "security":[], "tags":[] }
-
This might be a nice-to-have but I don’t think it’s necessary. And it also worries me a bit that effectively having two definitions of the endpoints could be problematic, because we’d have to keep them in sync.
I propose that we close this issue on that basis.
-
reporter
I completely agree, I updated this issues as discussed during a wg meet, at the request to do so I promised to do it :)
Let’s close it -
reporter
- changed status to resolved
- Log in to comment
- Assignee
- –
- Type
- Priority
- Status
- resolved
- Component
- Federation
- Milestone
- –
- Version
- –
- Votes
- 0
- Watchers
- 1
According to what was discussed during the meeting of January 25, 2022, we will enrich this issue with an example of an Openapi Schema v3 before deciding whether it is worth it