obf-connector/readme.md

An API connector for Open Badge Factory

# OBF Connector

An API connector for Open Badge Factory.

This repo contains a specification and a reference implementation for OBF in [lib/obf/](lib/obf/).

Useage:

```JavaScript
const OBFConnector = require('obf-connector');
const connector = new OBFConnector('your_org_id', 'path/to/cerificate', 'path/to/private.key');
connector.getEarnableBadges((err, response) => {
  if (err) throw err;
  console.dir(response);
});
```

See [index.js](index.js) for more examples.


## Design Philosophy

This is an implementation an abstract connector specification. Rather than providing abstract classes from which to inherit, the specification will be outlined below (or maybe in the future at some other place) and the implementation will adhere to it as close as possible. This has the rationale that JavaScript, unlike strongly typed languages like Java, does not impose type checking at compiletime, thus removing the need for something like an interface definition.

The basic idea is that there are multiple [Open Badges](https://openbadges.org/) systems like [Open Badge Factory](https://openbadgefactory.com/), [Credly](https://credly.com/) and [Badgr](https://badgr.io/) (*background systems* or *target systems*). Most of these systems provide similar functionalities through their APIs, like *creating Badges*, *listing Badges of an issuer* and *applying for badges*. A *connecting system* might want to use some of that functionality, while being loosely coupled to a specific *target system*.

The Connector gets a command describing a use case to be realized by the background system with the id of the current user and required parameters.The Connector handles the login into the Background system and requests, if necessary, from KO-Badgelor a screen area to let the Background system communicate with the user.
The Connector informs KO-Badgelor when the Background system has completed the use case by returning an instance of class ConnectorResponse

Note that most systems still use the `1.1` specification, so that's what we'll use too.



## Specification

Following this specification should make it possible for users of an implementation to easily switch to another implementation. For that, we define a common interface below, which is some classes with serveral defined functions or fields. Some functions may be left unimplemented but should throw a `ReferenceError` when called. This is meant to be a guideline that leaves most specifics to the implementation. It is designed to be broken, but as little as possible, as to minimize switching costs.

Development of the specification is guided by <https://userpages.uni-koblenz.de/~dahn/Badgelor/>.


### `Badge`

A representation of a badge, possibly with information on how to earn it. Can be an Open Badges Badge: https://openbadgespec.org/history/1.1-specification.html#BadgeClass.

Must have and `id` field.


### `User`

An user in the connecting system, independent of a role.

Must have and `id` field.


### `Filter`

A plain JavaScript object. Each present property will be matched against a target collection. Example:

```JavaScript
const filter = {
  "issuer": "jake",
  "lecture": "echeladder"
}
```

Should return elements of a collection whose `issuer` property equals `jake` and whose `lecture` property equals `echeladder`.


### `Connector`

Provides functions to work with a Open Badges system.

#### `Connector#addCreator(creator: User)`

Creates the user `creator` in the target system.

#### `Connector#applyForBadge(user: User, badge: Badge)`

Creates an application from `user` for `badge`:

#### `Connector#createBadge(user: User, badge: Badge)`

Creates `badge` with `user`'s account'.

#### `Connector#getBadgesList(user: User, filter: Filter)`

Reads the list of available badges that the user is allowed to see. For example, this may exclude unpublished badges. The badges may be earnable. Uses filter to filter the result. Whether the filtering is done in the connector or in the target system is left to the implementation.

#### `Connector#getCreatorsList(filter: Filter)`

Returns a filtered list of creator user accounts in the target system. Whether the filtering is done in the connector or in the target system is left to the implementation.

#### `Connector#modifyBadge(user: User, badge: Badge)`

Updates the data of `badge` (identified by its `id`) with the new data from `badge`. The action is executed as `user`, if possible.

#### `Connector#modifyCreator(creator: User)`

Updates the data of `creator` (identified by their `id`) with the new data from `creator`.

#### `Connector#pushBadge(user: User, badge: Badge, target: URL)`

Facilitates pushing `badge`, owned by `user` to the `target` backpack/passport server.

#### `Connector#reviewApplications(user: User, badge: Badge)`

Initiates the process of the user reviewing applications. For example it may open a connection to the background system with the user logged in and the list of applicants for the specific badge open