kpm-api v0.3.0
KPM-API
KPM-API is a set of Connect middleware for implementing the API required to host a KSP Packaged Module repository.
The API has several sub components that can be individually implemented:
- Configuration - A way to expose the capabilities of the repository to clients.
- Packages - The consumption end of the API and is expected to be supported.
- Publishing - Allows creators to submit their modules to the repository.
- Owner - Allows project owners to distribute control over a package .
Installation
Install through npm
like so:
npm install kpm-api --save
Feature: Configuration
If you wish to mount the middleware on endpoints different from the defaults or wish to only implement certain API's, you can use the config
middleware to make the clients aware. The middleware serves a file(/kpm-config.json
) that is requested by the kpm client to determine the repository capabilities and conventions.
Example
app.use(kpm.config({
packages: '/p',
owner: false,
publishing: false
}));
Options
packages - packages API feature endpoint path. By default, the path is set to
/p
.owner - owner API feature endpoint path. By default, this feature is disabled.
publishing - publishing API feature endpoint path. By default, this feature is disabled.
Note 1: All paths are relative to the host. Absolute URI's are not allowed.
Note 2: A false
value indicates that feature is not available on this registry.
Feature: Packages
This feature handles requests for retrieving and searching for packages.
Example
var express = require('express'),
kpm = require('kpm-api'),
app = express();
app.use(kpm.packages({
list: function (pageIndex, pageSize, client, callback) {
// code to retrieve a list of available packages.
// pass result to callback when done.
callback([]);
},
fetch: function (pkg, client, callback) {
// code to retrieve a stream or buffer for the
// specified package and version. pass result to
// callback when done.
callback(null); // package not found.
},
exists: function (pkg, client, callback) {
// code to determine whether specified package exists.
// return result (either true or false) to callback.
callback(false);
}
});
Options
list - A handler for listing available packages in the repository.
pageSize
will be-1
if not specified. This would mean paging is not active.callback
expects anArray
.callback
will return an emptyArray
if the result isnull
orundefined
.pageIndex
is zero-based.
fetch - a handler for retrieving a package.
callback
expects astream.Readable
,Buffer
, orString
.- a
String
result will cause a redirection to the url in theString
. - a
null
orundefined
result means the package was not found and the server will respond with 404. - if the result is not a
stream
orBuffer
, the middleware will pass an error to the next middleware.
exists - a handler for determining if a package is available within the repository. Like fetch, it takes a pkg
object, client
object, and callback
.
callback
expects eithertrue
orfalse
.
Feature: Owners
This feature is responsible for adjusting and displaying what users can publish a specific package to the repository. It is meant to allow users to manipulate publishing rights on a repository from the client. The rights granted at this time are all or nothing. A user with owner rights to a repository can publish new versions of the package to the repository.
Example
var express = require('express'),
kpm = require('kpm-api'),
app = express();
app.use(kpm.owner({
add: function(pkg, client, userName, callback) {
},
remove: function(pkg, client, userName, callback) {
},
list: function(pkg, client, callback) {
}
}));
Options
add - a handler for adding a user to a package's owner list.
callback
expects eithertrue
orfalse
to indicate success.
remove - a handler for removing a user from a package's owner list.
callback
expects eithertrue
orfalse
to indicate success.
list - a handler to list owners of a package.
callback
expects anArray
.callback
will return an emptyArray
if the result isnull
orundefined
.
Feature: Publishing
This feature allows users to publish/unpublish packages to the repository from the KPM client.
Example
Example
var express = require('express'),
kpm = require('kpm-api'),
app = express();
app.use(kpm.publishing({
publish: function (pkg, client, stream, callback) {
},
unpublish: function (pkg, client, callback) {
},
uploadResolver: function(req, fieldName) {
}
}));
Options
publish - a handler to adding the package to the repository. Takes a pkg
object, a client
object, stream
object, and a callback
for returning the result.
callback
expects eithertrue
orfalse
to indicate success.
unpublish (optional) - a handler for removing the package from the repository. Takes pkg
object, client
object, and a callback
for returning the result.
callback
expects eithertrue
orfalse
to indicate success.
uploadResolver (optional)- a handler that resolves the package stream from the current request. It takes the current request(req
) and the name(fieldName
) of the field where the package stream should be located. This is a synchronous call and expects a return value to be the resolved stream of the package. A default implementation is provided if not specified which looks in req.files
for the file stream.
- the returned value must be an instance of
stream.Readable
to be used by the middleware.
Key Verification
The owner and publishing features require a handler to verify client requests. This handler can be specified using the verifyKey
function.
Usage
require('kpm-api').verifyKey(function (key, callback) { /* ... */ });
Example
var kpm = require('kpm-api');
kpm.verifyKey(function (key, callback) {
// verify key provided
callback(true || false);
});
Parameters
handler - the handler will be passed a key
and a callback
. After verifying the key, the result should be passed to callback
as a boolean (true
or false
).
Types
Client
Read-Only Information related to the KPM client responsible for the current API request.
Usage
var Client = require('kpm-api').Client;
var client = new Client(/* request object */);
Members
- id: String | Null - the user-agent string of the KPM client. May be empty if not provided.
- version: String | Null - the version of the KPM client. May be null if not provided.
- key: String | Null - the API key provided by the client. May be null if not provided.
Package
Usage
var Package = require('kpm-api').Package;
var pkg = new Package(id, version);
Members
- id: String | Null - the id of the package. May be null if the id was not provided by the request.
- version: String | Null - the version of the package. An empty string implies the latest version.
Bugs and Feedback
If you see a bug or have a suggestion, feel free to create an issue here.
License
MIT License. Copyright 2014 Daniel Krainas http://www.danielkrainas.com