api.yaml

###
### 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"