{ "openapi" : "3.0.0", "info" : { "version" : "2.1", "title" : "Open Badges OpenAPI (JSON) Definition", "description" : "Open Badges Connect is a secure REST interface for exchanging Open Badges.", "termsOfService" : "https://www.imsglobal.org/license.html", "contact" : { "name" : "Lisa Mattson (COO), IMS Global ", "url" : "http://www.imsglobal.org", "email" : "lmattson@imsglobal.org" }, "license" : { "name" : "IMS Global", "url" : "https://www.imsglobal.org/license.html" } }, "servers" : [ { "url" : "https://{hostName}{basePath}", "description" : "The pattern for the Server URL should be configured for the actual server location.", "variables" : { "hostName" : { "description" : "This is the hostname for the server and MUST be set to the actual service provider (the IMS url is given as a default value).", "default" : "www.imsglobal.org" }, "basePath" : { "description" : "This is the base-path for the full URL and MUST be a part of the service endpoints.", "enum" : ["/ims/ob/v2p1/"], "default" : "/ims/ob/v2p1/" } } } ], "tags" : [ { "name" : "OBC-Manifest", "description" : "Open Badges Connect manifest interface." }, { "name" : "OBC-Service", "description" : "Open Badges Connect service interface." } ], "paths" : { "/.well-known/badgeconnect.json" : { "get" : { "operationId" : "getManifest", "summary" : "The REST read request message for the getManifest() API call.", "tags" : [ "OBC-Manifest" ], "description" : "Open Badges Connect Service manifest read operation.", "responses" : { "200" : { "description" : "This is the response when the request has been completed successfully.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ManifestDType" } } } }, "404" : { "description" : "This is the response when the provider does not support the badge connect API." }, "421" : { "description" : "This is the response when the request was not made over secure TLS protocol." }, "default" : { "description" : "This is the response when some other error has occured." } } } }, "/assertions" : { "get" : { "operationId" : "getAssertions", "summary" : "The REST read request message for the getAssertions() API call.", "tags" : [ "OBC-Service" ], "description" : "Fetch Assertions for the supplied parameters and authentication token.", "parameters" : [ { "name" : "limit", "in" : "query", "description" : "Indicate how many results should be retrieved in a single page.", "required" : false, "schema" : { "type" : "integer", "format" : "int32", "minimum" : 1 }, "style" : "form", "allowEmptyValue" : false }, { "name" : "offset", "in" : "query", "description" : "Indicate the index of the first record to return (zero indexed).", "required" : false, "schema" : { "type" : "integer", "format" : "int32", "minimum" : 0 }, "style" : "form", "allowEmptyValue" : false }, { "name" : "since", "in" : "query", "description" : "Retrieve Assertions that were created or updated after the provided timestamp. Must be an ISO 8601 compatible timestamp with a time zone indicator.", "required" : false, "schema" : { "type" : "string", "format" : "date-time" }, "style" : "form", "allowEmptyValue" : false } ], "security" : [ { "OAuth2ACG" : [ "https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.readonly" ] } ], "responses" : { "200" : { "description" : "This is the response when the request has been completed successfully.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssertionsResponseDType" } } }, "headers" : { "X-Total-Count" : { "description" : "The total number of resources that are available to be returned", "schema" : { "type" : "integer" } } }, "links" : { "next" : { "description" : "Get the next set of resources i.e. from offset to offset+limit", "operationId" : "getAssertions", "parameters" : { "limit" : "$request.path.limit", "offset" : "$request.path.offset" } }, "last" : { "description" : "Get the last set of resources i.e. from offset to end", "operationId" : "getAssertions", "parameters" : { "limit" : "$request.path.limit", "offset" : "$request.path.offset" } }, "first" : { "description" : "Get the first set of resources i.e. from first to limit", "operationId" : "getAssertions", "parameters" : { "limit" : "$request.path.limit", "offset" : "$request.path.offset" } }, "prev" : { "description" : "Get the previous set of resources i.e. from last_offset to last_offset+limit", "operationId" : "getAssertions", "parameters" : { "limit" : "$request.path.limit", "offset" : "$request.path.offset" } } } }, "400" : { "description" : "An invalid request was made.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "401" : { "description" : "The request was not correctly authorized.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "404" : { "description" : "The requested resource does not exist.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "405" : { "description" : "This method is not allowed on the endpoint.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "500" : { "description" : "This code should be used only if there is catastrophic error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "default" : { "description" : "Any other response." } } }, "post" : { "operationId" : "postAssertion", "summary" : "The REST update request message for the postAssertion() API call.", "tags" : [ "OBC-Service" ], "description" : "Create or update an Assertion.", "security" : [ { "OAuth2ACG" : [ "https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.create" ] } ], "requestBody" : { "description" : "The Assertion to be created or updated. Data MUST be a list exactly one Assertion long.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AssertionPayloadDType" } } }, "required" : true }, "responses" : { "200" : { "description" : "The Assertion was updated successfully.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "400" : { "description" : "An invalid request was made.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "401" : { "description" : "The request was not correctly authorized.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "404" : { "description" : "The requested resource does not exist.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "405" : { "description" : "This method is not allowed on the endpoint.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "500" : { "description" : "This code should be used only if there is catastrophic error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "default" : { "description" : "Any other response." } } } }, "/profile" : { "get" : { "operationId" : "getProfile", "summary" : "The REST read request message for the getProfile() API call.", "tags" : [ "OBC-Service" ], "description" : "Fetch the profile for the supplied authentication token.", "security" : [ { "OAuth2ACG" : [ "https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.readonly" ] } ], "responses" : { "200" : { "description" : "This is the response when the request has been completed successfully.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProfileResponseDType" } } } }, "400" : { "description" : "An invalid request was made.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "401" : { "description" : "The request was not correctly authorized.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "404" : { "description" : "The requested resource does not exist.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "405" : { "description" : "This method is not allowed on the endpoint.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "500" : { "description" : "This code should be used only if there is catastrophic error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "default" : { "description" : "Any other response." } } }, "post" : { "operationId" : "postProfile", "summary" : "The REST update request message for the postProfile() API call.", "tags" : [ "OBC-Service" ], "description" : "Update the profile for the authenticated user.", "security" : [ { "OAuth2ACG" : [ "https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.update" ] } ], "requestBody" : { "description" : "The authenticated user's profile.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProfileDType" } } }, "required" : true }, "responses" : { "200" : { "description" : "This is the response when the request has been completed successfully.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ProfileResponseDType" } } } }, "400" : { "description" : "An invalid request was made.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "401" : { "description" : "The request was not correctly authorized.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "404" : { "description" : "The requested resource does not exist.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "405" : { "description" : "This method is not allowed on the endpoint.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/StatusResponseDType" } } } }, "500" : { "description" : "This code should be used only if there is catastrophic error." }, "default" : { "description" : "Any other response." } } } } }, "components" : { "securitySchemes" : { "OAuth2ACG" : { "type" : "oauth2", "description" : "Authorization Code Grant (ACG) security scheme per IMS Security Framework.", "flows" : { "authorizationCode" : { "tokenUrl" : "/token", "authorizationUrl" : "/authorize", "refreshUrl" : "/token", "scopes" : { "https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.create" : "Permission to create assertions for the authenticated entity.", "https://purl.imsglobal.org/spec/ob/v2p1/scope/assertion.readonly" : "Permission to read assertions for the authenticated entity.", "https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.readonly" : "Permission to read the profile for the authenticated entity.", "https://purl.imsglobal.org/spec/ob/v2p1/scope/profile.update" : "Permission to update the profile for the authenticated entity." } } } } }, "schemas" : { "AssertionDType" : { "description" : "Open Badges 2.0 Assertion object.", "type" : "object", "properties" : { "id" : { "description" : "Model Primitive Datatype = NormalizedString. Unique IRI for this object.", "type" : "string" }, "type" : { "description" : "Model Primitive Datatype = String. The JSON-LD type of this object. Normally 'Assertion'.", "type" : "string" } }, "required" : [ "id","type" ], "additionalProperties" : true }, "AssertionPayloadDType" : { "description" : "The payload for the POST /assertions endpoint.", "type" : "object", "properties" : { "assertion" : { "$ref" : "#/components/schemas/AssertionDType" }, "signedAssertion" : { "description" : "Model Primitive Datatype = String. A signed assertion in JWS Compact Serialization format.", "type" : "string" } }, "additionalProperties" : false }, "AssertionsResponseDType" : { "description" : "Response payload for the GET /assertions endpoint.", "type" : "object", "properties" : { "status" : { "$ref" : "#/components/schemas/StatusDType" }, "assertions" : { "description" : "An array of unsigned assertions in JSON-LD serialization format.", "type" : "array", "minItems" : 0, "items" : { "$ref" : "#/components/schemas/AssertionDType" } }, "signedAssertions" : { "description" : "Model Primitive Datatype = String. An array of signed assertions in JWS Compact Serialization format.", "type" : "array", "minItems" : 0, "items" : { "type" : "string" } } }, "required" : [ "status" ], "additionalProperties" : false }, "BadgeConnectAPIDType" : { "description" : "Configuration information about a single implementation.", "type" : "object", "properties" : { "id" : { "description" : "Model Primitive Datatype = NormalizedString. Unique IRI for the configuration.", "type" : "string" }, "type" : { "description" : "Model Primitive Datatype = NormalizedString. The JSON-LD type of this object. Normally 'BadgeConnectAPI'.", "type" : "string" }, "apiBase" : { "description" : "Model Primitive Datatype = AnyURI. Fully qualified URL that will be concatenated with the API endpoints. It SHOULD NOT have a trailing slash '/'. E.g. apiBase + '/assertions'.", "type" : "string", "format" : "uri" }, "authorizationUrl" : { "description" : "Model Primitive Datatype = AnyURI. A fully qualified URL to the host's authorization endpoint.", "type" : "string", "format" : "uri" }, "image" : { "description" : "Model Primitive Datatype = AnyURI. An image representing the platform. May be a URI to a hosted image or a Data URI.", "type" : "string", "format" : "uri" }, "name" : { "description" : "Model Primitive Datatype = String. The name of the platform supporting the API. This SHOULD reflect the user-facing identity of the platform requesting authorization.", "type" : "string" }, "privacyPolicyUrl" : { "description" : "Model Primitive Datatype = AnyURI. A fully qualified URL to the platform's privacy policy. Other platforms SHOULD link to this resource as part of their authorization interface.", "type" : "string", "format" : "uri" }, "registrationUrl" : { "description" : "Model Primitive Datatype = AnyURI. A fully qualified URL to the host's dynamic client registration endpoint.", "type" : "string", "format" : "uri" }, "scopesOffered" : { "description" : "Model Primitive Datatype = AnyURI. Applies to Hosts only. An array of strings listing the scopes supported by the Host in the form of fully qualified URLs to the scope descriptors.", "type" : "array", "minItems" : 1, "items" : { "type" : "string", "format" : "uri" } }, "termsOfServiceUrl" : { "description" : "Model Primitive Datatype = AnyURI. A fully qualified URL to the platform's terms of service. Other platforms SHOULD link to this resource as part of their authorization interface.", "type" : "string", "format" : "uri" }, "tokenRevocationUrl" : { "description" : "Model Primitive Datatype = AnyURI. A fully qualified URL to the host's token revocation endpoint.", "type" : "string", "format" : "uri" }, "tokenUrl" : { "description" : "Model Primitive Datatype = AnyURI. A fully qualified URL to the host's token request endpoint for exchanging an authorization code for a bearer token.", "type" : "string", "format" : "uri" }, "version" : { "description" : "Model Primitive Datatype = String. A string representing the implemented version. MUST be in the format of vMAJORpMINOR where MAJOR and MINOR are integers.", "type" : "string" } }, "required" : [ "apiBase","authorizationUrl","name","privacyPolicyUrl","registrationUrl","scopesOffered","termsOfServiceUrl","tokenUrl","version" ], "additionalProperties" : false }, "ManifestDType" : { "description" : "Provider configuration information. A provider may support multiple implementations.", "type" : "object", "properties" : { "id" : { "description" : "Model Primitive Datatype = NormalizedString. Unique IRI for the manifest.", "type" : "string" }, "type" : { "description" : "Model Primitive Datatype = NormalizedString. The JSON-LD type of this object. Normally 'Manifest'.", "type" : "string", "default" : "Manifest" }, "badgeConnectAPI" : { "description" : "Set of BadgeConnectAPI configurations.", "type" : "array", "minItems" : 1, "items" : { "$ref" : "#/components/schemas/BadgeConnectAPIDType" } } }, "required" : [ "id","badgeConnectAPI" ], "additionalProperties" : false }, "ProfileDType" : { "description" : "Open Badges 2.0 Profile object.", "type" : "object", "properties" : { "id" : { "description" : "Model Primitive Datatype = NormalizedString. Unique IRI for this object.", "type" : "string" }, "type" : { "description" : "Model Primitive Datatype = String. The JSON-LD type of this object. Normally 'Profile'.", "type" : "string" } }, "required" : [ "id","type" ], "additionalProperties" : true }, "ProfileResponseDType" : { "description" : "The response to both the GET /profile and POST /profile endpoints.", "type" : "object", "properties" : { "status" : { "$ref" : "#/components/schemas/StatusDType" }, "profile" : { "$ref" : "#/components/schemas/ProfileDType" } }, "required" : [ "status" ], "additionalProperties" : false }, "StatusDType" : { "description" : "Response status.", "type" : "object", "properties" : { "error" : { "description" : "Model Primitive Datatype = String. A nullable string and the human-readable message describing the problem.", "type" : "string" }, "statusCode" : { "description" : "Model Primitive Datatype = Integer. The HTTP status code of the response.", "type" : "integer", "format" : "int32" }, "statusText" : { "description" : "A string matching one of the enumerated and allowed values for the given endpoint.", "type" : "string", "enum" : [ "OK","REQUEST_VALIDATION_ERROR","RECIPIENT_PROFILE_MISMATCH","INVALID_BADGE","BAD_REQUEST","UNAUTHENTICATED","PERMISSION_DENIED","NOT_FOUND","METHOD_NOT_ALLOWED" ] } }, "required" : [ "statusCode" ], "additionalProperties" : false }, "StatusResponseDType" : { "description" : "A status-only response.", "type" : "object", "properties" : { "status" : { "$ref" : "#/components/schemas/StatusDType" } }, "required" : [ "status" ], "additionalProperties" : false } } } }