webservices

A web-service is a function that can be called outside of Marjory

The webservices directory contains your web-services functions. Marjory reads all the .js files inside this directory and automatically creates the web-services for you.

A web-service is and exported function that exists inside of the webservices folder. You do not have to write only one web-service per file, but we recommend doing so as it will keep your code clean.

If you do not export your function, it will not be defined as a web-service

// This is a web-service, because it's exported
export const getPancakes = (data, credentials) =>
  new ModuleResponse({ pancakes: ["🥞", "🥞", "🥞", "🥞"] });

// This is not a web-service, because it's not exported
const getPancake = (data, credentials) => new ModuleResponse({ pancake: "🥞" });

Properties

data

The property data contains all the inputs of a web-service. To know more about prescript, see How to add and configure a service action

Here is an example of a marjory.yml web-service section and the object you can work with in a web-service function:

marjory.yml

...
webservices:
  getPancake:
    name: Get Pancake
    inputs:
      topping:
        type: string
        descripton: The topping you want on your pancake
        required: true
        example: BUTTER
...

webservice.js

export const getPancake = ({ topping }, credentials) =>
    new ModuleResponse({ pancake: "🥞", topping });

credentials

The property credentials contains all the credentials information defined when the module was installed by someone. The list of given credentials are defined in the marjory.yml file.

Here is an example of a marjory.yml credentials section and the object you can work with in a web-service function:

marjory.yml

...
credentials:
  apiKey:
    type: string
    isCrypt: true
    description: The api key to work with the Pancake API
...

webservice.js

export const orderPancake = (data, { apiKey }) => {
  // apiKey : string
  var user = authenticateUser(apiKey)
  
  var pancake = getPancakeForUser(user);

  return new ModuleResponse(pancake);
}

SDK

ModuleResponse

ModuleResponse is a simple class allowing you to return data (object or basic type) to user calling the web-service. This will return an object with the data passed and a status code of 200.

ModuleError

ModuleError is to handle your web-service errors, it's like an HTTP error. Here is an example:

import Marjory from "marjory";

export const getPancake = (data) => {
  var pancake = getPancake(data.id);
  
  if (!pancake)
    throw new Marjory.ModuleError(404, `No pancake with id ${data.id}`);

  return new Marjory.ModuleResponse(response);
}

If no pancake is found, this will return an object with a 404 status code and a data object containing the message.

Storage

You might need to keep storage between multiple action execution for the same operator. You can do so by using the DB object of the SDK.

Here is all the functions you can use on the DB object:

import Marjory from "marjory";

export const webService = (data, credentials) => {
    const { DB } = Marjory;
    
    // Search
    DB.collection('pancakes').find();
    DB.collection('pancakes').findOne();
    
    // Insertion
    DB.collection('pancakes').insertOne();
    DB.collection('pancakes').insertMany();
    
    // Update
    DB.collection('pancakes').updateOne();
    DB.collection('pancakes').updateMany();
    DB.collection('pancakes').replaceOne();
    DB.collection('pancakes').findOneAndUpdate();
    DB.collection('pancakes').findOneAndReplace();
    
    // Deletion
    DB.collection('pancakes').deleteOne();
    DB.collection('pancakes').deleteMany();
    DB.collection('pancakes').findOneAndDelete();
    
    // Stats
    DB.collection('pancakes').countDocuments();
    DB.collection('pancakes').estimatedDocumentCount();
}

Do not use const { DB } = Marjory from outside your function

Behind the DB object is a MongoDB instance. You can learn more on how to use these functions directly from mongo documentation.