Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

campsi

Package Overview
Dependencies
Maintainers
0
Versions
135
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

campsi

Configurable API for managing and publishing document-oriented content

  • 5.14.5
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
21
decreased by-87.79%
Maintainers
0
Weekly downloads
 
Created
Source

campsi/api

Greenkeeper badge Build Status

Manage and expose document-oriented content through a configurable RESTful API.

Features

API
  • Store and manage both collections or individual documents
  • Describe complex data structures, using campsi components
  • State-based document lifecycle for approval workflows
  • POST, PUT and DELETE asynchronous webhooks for distributed architecture
  • Truly Stateless
  • Patch updates
  • Conflicts resolver
Querying
  • Embed related documents ?embed=shippingAddresses
  • Complex filtering ?data.name=Thomas&data.address.city=London
  • Complex sorting ?sort=name,-birthday
  • Pagination ?page=4&perPage=20
  • Stored searches
Authentication & authorization
Other
  • Swagger / API doc generation
  • Generate random mock data
Assets Management
  • Stream based upload system
  • Filtered and paginated GET route
  • Custom storage adapters
  • GraphicsMagick Metadata recognition
  • Resize and convert media derivatives

Concepts

States & role permissions

States represent the different stages in a document lifecycle, like published, draft and archived. To each state is associated specific role-based permissions, defining allowed HTTP methods :

MethodPossible actions on the state
GETview and query the documents
POSTcreate a new document
PUTedit an existing document or put a document in this state
DELETEdelete the state for the document

A document can be in different states at the same time, for example:

  1. the published version, visible on the website and the mobile app by everyone
  2. the waiting_for_approval version that has to be validated by an admin
  3. the new draft version an editor is already working on.

A document can migrate from a state to another, for example:

  • You create a resource ticket for your customers error reporting.
  • customer role is allowed to POST /docs/tickets in the default state submitted
  • support role is allowed to PUT /docs/tickets in the states replied or read

You can create any number of states:

  • published
  • draft
  • waiting_for_approval
  • approved
  • rejected
  • populationA
  • populationB
  • submitted
  • read
  • replied

You can create any number of roles:

  • admin
  • editor
  • manager
  • customer
  • user
  • public
  • visitor

Resource

The resource is the document template, it describes the fields and validation rules.

Document

A document is an instance of a resource. It has an id and a value for each defined state, which is encapsulated in a property named data.

Anatomy of a document
let doc = {
	id: new ObjectId("58205e4fa5dc6c3b381a0e9b"),
    states: {
    	published: {
        	createdAt: "2016-11-07 10:58:23.950Z",
            createdBy: "58277c406d6157a751399052",
            data: {
            	title: "Hello World",
                content: "I'm the published version"
            }
        },
    	draft: {
        	createdAt: "2016-11-07 11:22:12.950Z",
            createdBy: "58277c406d6157a751399052",
            data: {
            	title: "Hello World",
                content: "I'm the draft version"
            }
        },
    }
}

Relationships & document embedding

Relationships between resources are resolved:

  • automatically, if the relationship has the property embed set to true
  • on demand, if a embed={rel} parameter is passed in the query string

Because there are no JOIN in MongoDB, embedding documents requires the execution of supplementary queries. For performance reason, the results are memoized during the request lifetime.

Webhook

You can configure webhooks that are triggered when an request processed by campsi/api match a specific scope (action, state, resource). Once triggered, the webhook send an asynchronous HTTP request to the endpoint uri specified in its configuration.

todo distributed architecture example

Usage

First, start Redis and MongoDB containers by running:

docker compose up -d

To stop the containers, run:

docker compose down

To restart the containers, run:

docker compose restart

Once the containers are running, you can start the server by running:

npm run test

Flags

--schema     "path/to/the/schema.json"  # specifies the json schema to use
--port       3000                       # set the HTTP port to listen to
--data       "/mnt/nfs/data"            # repository for upload

campsi/schema specification

Root
PropertyTypeDescription
nameStringunique identifier of your api
titleStringtitle of the API
descriptionStringmarkdown description
roles<Role>roles hashmap
types<ResourceType>resource types hashmap
resources<Resource>resources hasmap
Role
PropertyTypeDescription
labelStringunique identifier of your api
authBooleantitle of the API
adminBooleanmarkdown descripition
ResourceType
PropertyTypeDescription
defaultStateStringname of the state any request will default to
states<State>hashmap of the states
permissions<Role, <State, Method>>Allowed HTTP methods by role and by state
State
PropertytypeDescription
nameStringname of the state any request will default to
labelStringhashmap of the states
validateBooleanwether the data has to be valid to be saved or not
Resource
PropertytypeDescription
titleStringreadable title
descriptionStringmarkdown description
typeStringname of the ResourceType
fields[Object]list of the fields composing the model
hooks[Hook]list of hooks bound to the resource
rels<Rel>hashmap of relationships
Rel
PropertytypeDescription
pathStringproperty path
resourceStringname of the resource it points to (self reference is OK)
embedBooleanresolve relation automatically
fields[String]list of the fields that gets embedded
Hook
PropertytypeDescription
nameStringhook identifier
uriStringtodo support parameter
methodStringone of POST GET PUT DELETE
payloadBooleanif true and method is POST or PUT, send the data
on[String]list of actions
states[String]list of states
retryNumbernumber of time the HTTP client tries to reach the endpoint
timeoutNumbernumber of seconds before the HTTP client hangs up
headers<String,String>hashmap of the request headers

Requirements

  • NodeJS v16.0.0
  • MongoDB v2.6.0
  • Optional
    • ImageMagick
    • Graphics Magick

FAQs

Package last updated on 23 Oct 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc