Skip to content
This repository was archived by the owner on Sep 2, 2020. It is now read-only.

Latest commit

 

History

History
378 lines (300 loc) · 8.5 KB

programs.md

File metadata and controls

378 lines (300 loc) · 8.5 KB

Programs

Programs represent the lowest level of badging admin in BadgeKit. Each program belongs to one issuer, optionally along with other programs. Badges can be associated with a program, which could be a program of events grouping activities on a theme or subject area.

NAME VALUE
id integer - ID from database entry.
slug string - Short, computer-friendly name for the program. Used to identify program in API endpoints
url string - URL for the program.
name string - Name of the program.
description string - A short, human-friendly description of the program.
email string - Email address associated with the badge administrator of the program.
imageUrl string - Image for the program.

Endpoints

GET /systems/<slug>/issuers/<slug>/programs

Retrieves all available programs in the specified system and issuer.

Expected request

GET /systems/:systemSlug/issuers/:issuerSlug/programs

Available request parameters

  • page: - page of results to return
  • count: - count of results to return per page

e.g. /systems/<slug>/issuers/<slug>/programs?count=2&page=1

Expected response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "programs": [
  	{
  	  "id": 1,
  	  "slug": "program-slug",
  	  "url": "http://programsite.com",
  	  "name": "Program Name",
  	  "description": "Program description.",
  	  "email": "[email protected]",
  	  "imageUrl": "http://programsite.com/image.jpg"
  	},
  	...
  ],
  "pageData": {
    "page": 1,
    "count": 2,
    "total": 4
  }
}

pageData is returned when pagination parameters are used.

Response structure

  • programs [ ]
  • id
  • slug
  • url
  • name
  • description
  • email
  • imageUrl

Potential errors

None

GET /systems/<slug>/issuers/<slug>/programs/<slug>

Retrieves a specific program using its slug.

Expected request

GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug

Expected response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "program": {
    "id": 1,
    "slug": "program-slug",
    "url": "http://programsite.com",
    "name": "Program Name",
    "description": "Program description.",
    "email": "[email protected]",
    "imageUrl": "http://programsite.com/image.jpg"
  }
}

Response structure

  • program
  • id
  • slug
  • url
  • name
  • description
  • email
  • imageUrl

Potential errors

  • Program not found
  HTTP/1.1 404 Not Found
  Content-Type: application/json

  {
    "code": "ResourceNotFound",
    "message": "Could not find program field: `slug`, value: <attempted-slug>"
  }

POST /systems/<slug>/issuers/<slug>/programs

Creates a new program.

Expected request

POST /systems/:systemSlug/issuers/:issuerSlug/programs

Requests can be sent as application/json, application/x-www-form-urlencoded or multipart/form-data.

Parameters Required Description
slug required Short, computer-friendly name for the program. Good slugs are lowercase and use dashes instead of spaces, e.g. cpl-rahms-readers. Maximum of 50 characters and each program must have a unique slug.
name required Name of the program. Maximum of 255 characters.
url required URL for the program. Must be fully qualified, e.g. https://www.example.org, NOT just www.example.org.
description optional A short, human-friendly description of the program. Maximum of 255 characters
email optional Email address associated with the badge administrator of the program.
image optional Image for the program. Should be either multipart data or a URL.

Expected response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "status": "created",
  "program": {
    "id": 1,
    "slug": "program-slug",
    "url": "http://programsite.com",
    "name": "Program Name",
    "description": "Program description.",
    "email": "[email protected]",
    "imageUrl": "http://programsite.com/image.jpg"
  }
}

Response structure

  • status
  • program
    • id
    • slug
    • url
    • name
    • description
    • email
    • imageUrl

Potential errors

  • Invalid data
  HTTP/1.1 400 Bad Request
  Content-Type: application/json

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "message": "String is not in range",
        "field": "name",
        "value": "..."
      },
      ...
    ]
  }
  • Duplicate entry
  HTTP/1.1 409 Conflict
  Content-Type: application/json

  {
    "code": "ResourceConflict",
    "error": "program with that `slug` already exists",
    "details": {
      "slug": "program-slug",
      "name": "Program Name",
      "url": "http://programsite.com",
      "email": "[email protected]",
      "description": "Program description."
    }
  }

PUT /systems/<slug>/issuers/<slug>/programs/<slug>

Updates an existing program.

Expected request

PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug

Requests can be sent as application/json, application/x-www-form-urlencoded or multipart/form-data.

Parameters Description
slug Short, computer-friendly name for the program. Good slugs are lowercase and use dashes instead of spaces, e.g. cpl-rahms-readers. Maximum of 50 characters and each program must have a unique slug.
name Name of the program. Maximum of 255 characters.
url URL for the program. Must be fully qualified, e.g. https://www.example.org, NOT just www.example.org.
description A short, human-friendly description of the program. Maximum of 255 characters
email Email address associated with the badge administrator of the program.
image Image for the program. Should be either multipart data or a URL.

You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged.

Expected response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "updated",
  "program": {
    "id": 1,
    "slug": "program-slug",
    "url": "http://programsite.com",
    "name": "Updated Program Name",
    "description": "Updated program description.",
    "email": "[email protected]",
    "imageUrl": "http://programsite.com/image.jpg"
  }
}

Potential errors

  • Invalid data
  HTTP/1.1 400 Bad Request
  Content-Type: application/json

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "message": "String is not in range",
        "field": "name",
        "value": "..."
      },
      ...
    ]
  }
  • Duplicate entry
  HTTP/1.1 409 Conflict
  Content-Type: application/json

  {
    "code": "ResourceConflict",
    "error": "program with that `slug` already exists",
    "details": {
      "slug": "program-slug",
      "name": "Program Name",
      "url": "http://programsite.com",
      "email": "[email protected]",
      "description": "Program description."
    }
  }

DELETE /systems/<slug>/issuers/<slug>/programs/<slug>

Deletes an existing program.

Expected request

DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug

Expected response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "deleted",
  "program": {
    "slug": "program-slug",
    "name": "Program Name",
    "url": "http://programsite.com",
    "email": "[email protected]",
    "description": "Program description."
  }
}

Potential errors

  • Program not found
  HTTP/1.1 404 Not Found
  Content-Type: application/json

  {
    "code": "ResourceNotFound",
    "message": "Could not find program field: `slug`, value: <attempted-slug>"
  }