search

1EdTech / openbadges-discussion

A no-code repository for having discussions related to the general technical issues of openbadges.
10 stars 3 forks source link

OpenBadger API v3 [WIP] #3

Closed andrewhayward closed 7 years ago

andrewhayward commented 10 years ago

API v3 (candidate)

I'm posting this now, as a WIP, so it's at least out there, rather than sitting on my machine. Feel free to ignore, or dig in and tell me it's all wrong before it gets too late!

Introduction

This documentation describes a candidate for the Open Badger API (OBr), version 3. This version of the API takes lessons learned from both previous versions, uniting them into into a more rounded, general purpose suite.

Security Model

[TO DO]

Data

Issuers

[TO DO] This is not complete.

POST /v3/data/example-issuer

{
    "name": "Example Issuer",
    "strapline": "The best issuer in the world!",
    "description": "Example Issuer is strategically involved in issuing cutting edge badges, using the badging paradigm to think outside the box for a win-win situation."
}
Retrieving
GET /v3/data/example-issuer

{
    "name": "Example Issuer",
    "shortname": "example-issuer",
    "url": "http://example.org",
    "image": "http://example.org/media/images/logo.png",
    "strapline": "The best issuer in the world!",
    "description": "Example Issuer is strategically involved in issuing cutting edge badges, using the badging paradigm to think outside the box for a win-win situation.",
    "location": "/v3/data/example-issuer"
}

Programs

[TO DO] This is probably not complete.

POST /v3/data/example-issuer/example-program

{
    "name": "Example Program",
    "strapline": "The best program ever!",
    "description": "Example Issuer is running the Example Program to disrupt the core competencies of the badging space.",
}
Retrieving
GET /v3/data/example-issuer/example-program

{
    "name": "Example Program",
    "shortname": "example-program",
    "url": "http://example.org/programs/example",
    "image": "http://example.org/media/images/programs/example.png",
    "strapline": "The best program ever!",
    "description": "Example Issuer is running the Example Program to disrupt the core competencies of the badging space.",
    "location": "/v3/data/example-issuer/example-program",
    "issuer": {
        "name": "Example Issuer",
        "location": "/v3/data/example-issuer"
    }
}

Badges

[TO DO] This is probably not complete.

POST /v3/data/example-issuer/example-program/example-badge

{
    "name": "Example Badge",
    "url": "http://example.org/programs/example/badges/example",
    "image": "http://example.org/media/images/badges/example.png",
    "strapline": "A truly awesome badge",
    "description": "Ensuring deferred success to take it to the next level."
}
Retrieving
GET /v3/data/example-issuer/example-program/example-badge

{
    "name": "Example Badge",
    "shortname": "example-badge",
    "url": "http://example.org/programs/example/badges/example",
    "image": "http://example.org/media/images/badges/example.png",
    "strapline": "A truly awesome badge",
    "description": "Ensuring deferred success to take it to the next level."
    "criteria": "",
    "location": "/v3/data/example-issuer/example-program/example-badge",
    "issuer": {
        "name": "Example Issuer",
        "location": "/v3/data/example-issuer"
    },
    "program": {
        "name": "Example Program",
        "location": "/v3/data/example-issuer/example-program"
    },
    "meta": {...}
}

Meta

A namespaced JSON data blob, with optional schemas.

{
    "csol": {
        "tags": ["13-18", "S", "T", "online"],
        "ageRange": ["0-13", "13-18"],
        "type": "skill",
        "activityType": "online"
    },
    "geo": {
        "$schema": "http://json-schema.org/geo",
        "latitude": 51.507222,
        "longitude": -0.1275
    }
}

Global Response Information

Parameters

Every API request will have the following response parameters in common:

For paginatable requests, the following response parameters are also shared:

For paginatable requests, the following response headers are provided:

threeqube commented 10 years ago

@cmcavoy do we want to have the issuers have programs, programs have badges data model moving forward? Didn't that feel limiting with CEM and so forth?

cmcavoy commented 10 years ago

@threeqube worth thinking about, but not sure what an alternative is. If anything, the top level issuer needs more power if we're going to go multi-tenant in a bigger way (where tenants become whole city programs).

timothyfcook commented 7 years ago

Moving to archive.