With Carbon.io, APIs are defined via Services. A Service is an HTTP server that exposes a JSON REST API and which is defined as a tree of Endpoints. This Service defines a HTTP GET method on an Endpoint called "hello".
Each Endpoint is made up of Operations, which can formally define request parameters and responses. Operation definitions can use JSON Schemas to automatically validate input parameters and output responses.
Collections are a high-level abstraction on top of Endpoints that provide a higher-level interface for implementing access to a collection of resources. You can easily implement full database CRUD with virtually no code.
Every Carbon.io Service can be configured with an Authenticator. You can configure your own instance of the Authenticator class or use one of the several built-in Authenticators:
HttpBasicAuthenticator: Base class for implementing HTTP basic authentication
MongoDBHttpBasicAuthenticator: An HttpBasicAuthenticator backed by MongoDB
ApiKeyAuthenticator: Base class for implementing API-key based authentication
MongoDBApiKeyAuthenticator: An ApiKeyAuthenticator backed by MongoDB
Endpoints can configure an Access Control List (ACL) to govern which users can perform each HTTP operation.
HelloService.js
HelloEndpoint.js
const carbon = require('carbon-io')
const __ = carbon.fibers.__(module)
const o = carbon.atom.o(module).main
const _o = carbon.bond._o(module)
__(function() {
module.exports = o({
_type: carbon.carbond.Service,
port: 8888,
authenticator: o({
_type: carbon.carbond.security.MongoDBApiKeyAuthenticator,
apiKeyParameterName: 'api_key',
apiKeyLocation: 'header', // can be 'header' or 'query'
userCollection: 'users', // MongoDB collection where user objects are stored
apiKeyField: 'apiKey' // field that contains user api keys
}),
dbUri: 'mongodb://localhost:27017/mydb',
endpoints : {
hello: _o('./HelloEndpoint')
}
})
})
const carbon = require('carbon-io')
const __ = carbon.fibers.__(module)
const o = carbon.atom.o(module).main
module.exports = o({
_type: carbon.carbond.Endpoint,
acl: o({
_type: carbon.carbond.security.EndpointAcl,
groupDefinitions: { // This ACL defines a group called 'role'.
role: 'role' // We define a group called 'role' based on the user property named 'role'.
},
entries: [
{
user: { role: 'Writer' },
permissions: {
get: true,
post: true
}
},
{
user: { role: 'Reader' },
permissions: {
get: true,
post: false
}
}
]
}),
get: function(req) {
return { msg: 'Hello World!' }
},
post: function(req) {
return { msg: `Hello ${req.body.message}!` }
}
})
Every Carbon.io Service is capable of generating its own docs. You can currently choose between Github-flavored Markdown or static HTML using Aglio. The docs here are auto generated from our official tutorial.