confy-node

Official Confy API library client for node.js

This library is generated by alpaca

Installation

Make sure you have npm installed.

$ npm install confyio

Versions

Works with [ 0.10 / 0.12 / 4 / 6 ]

Usage

Before Starting

There are two ways of pointing to the credential document. You need to choose one of them.

User URL

Using user's authentication information

'https://user:[email protected]/orgs/orgname/projects/projectname/envs/envname/config'

Access Token URL

Using unique access token

'https://api.confy.io/orgs/orgname/config/abcdefabcdefabcdef1234567890abcdefabcdef'

Initiate API Client

var confy = require('confyio');

// When the document is the following
// => { 'port': 6000, 'db': { 'pass': 'sun' } }

Define Endpoint

You need to provide either an URL or an options objects to point the API client to the correct credential document.

// User URL
var endpoint = {
  user: 'user', // Username of the user trying to access the document
  pass: 'pass', // Password of the user trying to access the document
  org: 'company', // Name of the organization
  project: 'app', // Name of the project
  env: 'production', // Name of the stage
};

var endpoint = 'https://user:[email protected]/orgs/orgname/projects/projectname/envs/envname/config';

// Access Token URl
var endpoint = {
  org: 'company', // Name of the organization
  token: 'abcdefabcdefabcdef1234567890abcdefabcdef' // Access token of the document
};

var endpoint = 'https://api.confy.io/orgs/orgname/config/abcdefabcdefabcdef1234567890abcdefabcdef';

Call the Server

There are two ways of loading the credentials.

Data Object

You can load it as a hash object with the same structure into a variable.

confy.config.load(endpoint, function (err, config) {
  config.port // => 6000
  config.db.pass // => 'sun'
});

Environment Variables

You can load it directly into process.env with the key formed by concatenizing the path keys with underscores.

confy.config.env(endpoint, function (err) {
  // ['port']
  process.env.PORT // => 6000

  // ['db']['pass']
  process.env.DB_PASS // => 'sun'
});

API Reference

Build a client

Basic authentication

var auth = { username: 'pksunkara', password: 'password' };

var client = confy.client(auth, clientOptions);

Client Options

The following options are available while instantiating a client:

• base: Base url for the api
• api_version: Default version of the api (to be used in url)
• user_agent: Default user-agent for all requests
• headers: Default headers for all requests
• request_type: Default format of the request body

Response information

All the callbacks provided to an api call will receive the response as shown below

// You can also omit the 'methodOptions' param below
client.klass('args').method('args', methodOptions, function (err, response) {
    if (err) console.log(err);

    response.code;
    // >>> 200

    response.headers;
    // >>> {'x-server': 'apache'}
}

JSON response

When the response sent by server is json, it is decoded into a hash

response.body;
// >>> {'user': 'pksunkara'}

Method Options

The following options are available while calling a method of an api:

• api_version: Version of the api (to be used in url)
• headers: Headers for the request
• query: Query parameters for the url
• body: Body of the request
• request_type: Format of the request body

Request body information

Set request_type in options to modify the body accordingly

RAW request

When the value is set to raw, don't modify the body at all.

body = 'username=pksunkara';
// >>> 'username=pksunkara'

JSON request

When the value is set to json, JSON encode the body.

body = {'user': 'pksunkara'};
// >>> '{"user": "pksunkara"}'

Authenticated User api

User who is authenticated currently.

var user = client.user();

Retrieve authenticated user (GET /user)

Get the authenticated user's profile.

user.retrieve(options, callback);

Update authenticated user (PATCH /user)

Update the authenticated user's profile. Should use basic authentication.

The following arguments are required:

user.update(options, callback);

Organizations api

Organizations are owned by users and only (s)he can add/remove teams and projects for that organization. A default organization will be created for every user.

var orgs = client.orgs();

List Organizations (GET /orgs)

List all organizations the authenticated user is a member of.

orgs.list(options, callback);

Retrieve an organization (GET /orgs/:org)

Get the given organization if the authenticated user is a member.

The following arguments are required:

• org: Name of the organization

orgs.retrieve("big-company", options, callback);

Update an organization (PATCH /orgs/:org)

Update the given organization if the authenticated user is the owner. Email is the only thing which can be updated.

The following arguments are required:

• org: Name of the organization
• email: Billing email of the organization

orgs.update("big-company", "[email protected]", options, callback);

Teams api

Every organization will have a default team named Owners. Owner of the organization will be a default member for every team.

The following arguments are required:

• org: Name of the organization

var teams = client.teams("big-company");

List Teams (GET /orgs/:org/teams)

List teams of the given organization authenticated user is a member of.

teams.list(options, callback);

Create a team (POST /orgs/:org/teams)

Create a team for the given organization. Authenticated user should be the owner of the organization.

The following arguments are required:

• name: Name of the team
• description: Description of the team

teams.create("Consultants", "Guys who are contractors", options, callback);

Retrieve a team (GET /orgs/:org/teams/:team)

Get the given team in the given organization. Access only if the authenticated user is a member of the team.

The following arguments are required:

• team: Name of the team

teams.retrieve("consultants", options, callback);

Update a team (PATCH /orgs/:org/teams/:team)

Update the given team. Description is the only thing which can be updated. Authenticated user should be the owner of the organization.

The following arguments are required:

• team: Name of the team
• description: Description of the team

teams.update("consultants", "Guys who are contractors", options, callback);

Delete a team (DELETE /orgs/:org/teams/:team)

Delete the given team. Cannot delete the default team in the organization. Authenticated user should be the owner of the organization.

The following arguments are required:

• team: Name of the team

teams.destroy("consultants", options, callback);

List projects a team has access to (GET /orgs/:org/teams/:team/projects)

Retrieve the list of projects the given team has access to. Authenticated user should be a member of the team.

The following arguments are required:

• team: Name of the team

teams.projects("consultants", options, callback);

Members api

Teams contain a list of users. The Authenticated user should be the owner of the organization.

The following arguments are required:

• org: Name of the organization
• team: Name of the team

var members = client.members("big-company", "consultants");

List members (GET /orgs/:org/teams/:team/member)

List all the members in the given team. Authenticated user should be a member of the team or the owner of the org.

members.list(options, callback);

Add a member (POST /orgs/:org/teams/:team/member)

Add the user to the given team. The user in the request needs to be a string and be the username of a valid user. The Authenticated user should be the owner of the organization.

The following arguments are required:

• user: Username of the user

members.add("johnsmith", options, callback);

Remove a member (DELETE /orgs/:org/teams/:team/member)

Remove users from the given team. The user in the request needs to be a string and be the username of a valid user. Cannot delete the default member in a team. The Authenticated user should be the owner of the organization.

The following arguments are required:

• user: Username of the user

members.remove("johnsmith", options, callback);

Projects api

An organization can contain any number of projects.

The following arguments are required:

• org: Name of the organization

var projects = client.projects("big-company");

List projects (GET /orgs/:org/projects)

List all the projects of the given organization which can be accessed by the authenticated user.

projects.list(options, callback);

Create a project (POST /orgs/:org/projects)

Create a project if the authenticated user is the owner of the given organization. Only the owners team will be able to see the project initially.

The following arguments are required:

• name: Name of the project
• description: Description of the project

projects.create("Knowledge Base", "Support FAQ & Wiki", options, callback);

Retrieve a project (GET /orgs/:org/projects/:project)

Get the given project in the given organization. Works only if the authenticated user has access to the project.

The following arguments are required:

• project: Name of the project

projects.retrieve("knowledge-base", options, callback);

Update a project (PATCH /orgs/:org/projects/:project)

Update the given project. Description is the only thing which can be updated. Authenticated user should be the owner of the organization.

The following arguments are required:

• project: Name of the project
• description: Description of the project

projects.update("knowledge-base", "Support FAQ and Wiki", options, callback);

Delete a project (DELETE /orgs/:org/projects/:project)

Delete the given project. Authenticated user should be the owner of the organization.

The following arguments are required:

• project: Name of the project

projects.destroy("knowledge-base", options, callback);

Access api

List of teams whic have access to the project. Default team Owners will have access to every project. Authenticated user should be the owner of the organization for the below endpoints.

The following arguments are required:

• org: Name of the organization
• project: Name of the project

var access = client.access("big-company", "knowledge-base");

List teams (GET /orgs/:org/projects/:project/access)

Retrieve a list of teams which have access to the given project. Authenticated user should be a member of the team.

access.list(options, callback);

Add a team (POST /orgs/:org/projects/:project/access)

Give the team access to the given project. The team in the request needs to be a string and should be the name of a valid team. Authenticated user should be the owner of the organization.

The following arguments are required:

• team: Name of the team

access.add("consultants", options, callback);

Remove a team (DELETE /orgs/:org/projects/:project/access)

Remove project access for the given team. The team in the request needs to be a string and should be the name of a valid team. Can't delete default team's access. Authenticated user should be the owner of the organization.

The following arguments are required:

• team: Name of the team

access.remove("consultants", options, callback);

Environments api

Every project has a default environment named Production. Each environment has one configuration document which can have many keys and values.

The following arguments are required:

• org: Name of the organization
• project: Name of the project

var envs = client.envs("big-company", "knowledge-base");

List all environments (GET /orgs/:org/projects/:project/envs)

List all the environmens of the project. The authenticated user should have access to the project.

envs.list(options, callback);

Create an environment (POST /orgs/:org/projects/:project/envs)

Create an environment. The authenticated user should have access to the project.

The following arguments are required:

• name: Name of the environment
• description: Description of the environment

envs.create("QA", "Quality assurance guys server", options, callback);

Retrieve an environment (GET /orgs/:org/projects/:project/envs/:env)

Get the given environment in the given project. The authenticated user should have access to the project.

The following arguments are required:

• env: Name of the environment

envs.retrieve("qa", options, callback);

Update an environment (PATCH /orgs/:org/projects/:project/envs/:env)

Update the given environment. Description is the only thing which can be updated. Authenticated user should have access to the project.

The following arguments are required:

• env: Name of the environment
• description: Description of the environment

envs.update("qa", "Testing server for QA guys", options, callback);

Delete an environment (DELETE /orgs/:org/projects/:project/envs/:env)

Delete the given environment. Authenticated user should have access to the project. Cannot delete the default environment.

The following arguments are required:

• env: Name of the environment

envs.destroy("knowledge-base", options, callback);

Configuration api

Any member of the team which has access to the project can retrieve any of it's environment's configuration document or edit it.

The following arguments are required:

• org: Name of the organization
• project: Name of the project
• env: Name of the environment

var config = client.config("big-company", "knowledge-base", "production");

Retrieve a config (GET /orgs/:org/projects/:project/envs/:env/config)

Get an environment configuration

config.retrieve(options, callback);

Update the configuration (PATCH /orgs/:org/projects/:project/envs/:env/config)

Update the configuration document for the given environment of the project. We will patch the document recursively.

The following arguments are required:

• config: Configuration to update

config.update({
  database: {
    port: 6984
  },
  random: "wow"
}, options, callback);

Retrieve config versions (GET /orgs/:org/projects/:project/envs/:env/versions)

List the last 10 versions of the environment configuration

config.versions(options, callback);

Contributors

Here is a list of Contributors

TODO

License

BSD

Bug Reports

Report here.

Contact

Pavan Kumar Sunkara ([email protected])