### ### Open Badges Peer Endorsment API Spec ### ### Note: WIP swagger: "2.0" info: description: "" version: "1.0.0" title: "" # TODO: Fill out # termsOfService: "http://swagger.io/terms/" # contact: # email: "apiteam@swagger.io" # license: # name: "Apache 2.0" # url: "http://www.apache.org/licenses/LICENSE-2.0.html" # host: "petstore.swagger.io" # basePath: "/v1" tags: - name: "assertion" description: "Everything about Badge Assertions" - name: "class" description: "Everything about Badge Classes" schemes: - "https" - "http" paths: /shares: post: tags: - "assertion" summary: "Share an Assertion" operationId: "shareAssertion" consumes: - "appliction/json" parameters: - in: "body" name: "body" description: "Pet object that needs to be added to the store" required: true schema: $ref: "#/definitions/Assertion" # TODO: Check error codes responses: 405: description: "Invalid input" 200: description: "The shared Assertion" schema: $ref: "#/definitions/Share" /shares/{shareId}: get: tags: - "assertion" summary: "Request an Assertion by it's id" operationId: "getAssertion" parameters: - name: "shareId" description: "The id of the Assertion you want to request" in: "path" required: true type: "string" # TODO: Check error codes responses: 200: description: "The requested Assertion" schema: $ref: "#/definitions/Share" /shares/{shareId}/endorse: post: tags: - "assertion" summary: "Submit an endorsment/signature" operationId: "submitSignedAssertion" parameters: - name: "shareId" description: "The id of the Assertion you want to endorse" in: "path" required: true type: "string" - name: "endorsment" description: "Endorsment data" in: "body" required: true schema: $ref: '#/definitions/Endorsment' # TODO: Check error codes responses: 200: description: "Succesful endorsment" # TODO: Check possible return value /classes: get: tags: - "class" summary: "Request the collection of Badge Classes" operationId: "getBadgeClasses" consumes: - "application/json" # TODO: Check error codes responses: 200: description: "The collection of Badge Classes" schema: type: "array" items: $ref: "#/definitions/BadgeClass" definitions: Share: type: object properties: id: $ref: "#/definitions/HashId" assertion: $ref: "#/definitions/Assertion" # TODO: Check required data Assertion: type: object properties: id: type: string format: uuid type: type: string enum: [Assertion] identity: $ref: "#/definitions/IdentityObject" badge: $ref: "#/definitions/BadgeClass" BadgeClass: type: object properties: type: type: string enum: [BadgeClass] image: type: string format: url example: "https://badgeframework/classes/coolclass" name: type: string example: "Demo Badge Creator" description: type: string example: "You can fluently create demo badges for demo purposes." issuer: type: string format: url example: "https://bskilled.com/profiles/abcd45a" criteria: type: string example: "You need to have created at least one demo badge." IdentityObject: type: object properties: identity: type: string format: email type: type: string enum: [email] hashed: type: boolean enum: [false] # TODO: Check required data Endorsment: type: object properties: signature: type: string HashId: type: string example: "fe3bb9ac" description: "A representation of the resource ID that is not just an incrementing number"