cake-service-express-api v0.3.0

cake microservices api

Description

cake is a microservices framework built with express and secret-stack. It uses event-sourcing/kappa architecture for triggering events, service discovery, and data propagation throughout the system. This repository contains the API Gateway for interacting with various microservices using a loose RPC API style.

API

The API listed below is specific to the cakemail service, but this will be made more generic in the future.

Authentication

All API requests should be accompanied by a jwt (json-web-token) as an Authorization: Bearer http header.

example

curl -X POST \
  http://localhost:3000/v1/publish/cakemail \
  -H 'Authorization: Bearer eyJhbGci.............cxMzM1NjA5fQ.Oh-cVF2trJUxBkZG1vYfSqZoaTkFPoBILtrqdskosCE'

POST /v1/publish/cakemail

Methods

sendEmail

The sendEmail method is responsible for sending email to individual, small group, or lists of contact. Attach a JSON body to a post request with a method property of sendEmail and a content property that contains a number of additional fields. content.type should always be @cake/send-email, the content.version is always 1.0.0. All fields are mandatory but Array's like content.to and content.lists can be empty Arrays.

{
	"method": "sendEmail",
	"content": {
        "type": "@cake/send-email",
        "version": "1.0.0",
        "from": "austin@z.g",
        "to": ["melddd@yellow.com"],
        "lists": ["!austins-crew!"],
        "text": "mellooooo",
        "subject": "testing stacks yall"
	}
}

example

curl -X POST \
  http://localhost:3000/v1/publish/cakemail \
  -H 'Authorization: Bearer eyJhbGci.............cxMzM1NjA5fQ.Oh-cVF2trJUxBkZG1vYfSqZoaTkFPoBILtrqdskosCE' \
  -H 'Content-Type: application/json' \
  -d '{
	"content": {
        "type": "@cake/send-email",
        "version": "1.0.0",
        "from": "austin@z.g",
        "to": ["mellow@yellow.com"],
        "lists": ["austins-crew"],
        "text": "mellooooo",
        "subject": "testing stacks yall"
	},
	"method": "sendEmail"
}'

updateContact

The updateContact method is used to add, update or delete contact details. Attach a body to the POST request containing a method property of updateContact and a content property. The content property has one property named batch which is an array of objects which represent the updates being made. An update object has the following properties.

• type: put for updates/additions, del for deletes
• org: the name of the organization this contact is being added to
• group: a segment or list this contact should be connected to
• userID: a unique ID for a user
• user: an object containing free form user data, ie. email, phone, first name. this is schemaless, but should at least contain an email. only needed for updates, not deletes

{
	"method": "updateContact",
	"content": {
		"batch": [
            {
                "type":"put",
                "org":"austins-crew",
                "group":"active",
                "userId":"bn0bv0r",
                "user": {
                    "email":"flickerlish@blorp.com"
                }
            },
            {
                "type":"del",
                "org":"austins-crew",
                "group":"active",
                "userId":"bp2bvcf",
            }
        ]
    }
}

usage

curl --location --request POST 'localhost:3000/v1/publish/cakemail' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1...............ZoaTkFPoBILtrqdskosCE' \
--data-raw '{
	"method": "updateContact",
	"content": {
		"batch": [
        {"type":"put","org":"austins-crew","group":"active","userId":"bn0bv0r","user":{
            "email":"flickerlish@blorp.com"
        }},
        {"type":"del","org":"austins-crew","group":"active","userId":"bp2bvcf"},
	]}
}
'

bulkLoad

The bulkLoad method addes support for importing contacts form a CSV document. It requires the file to be submitted with the multipart/form-data encoding. The CSV file should match the required fields for the update object included in the updateContacts call specifically, type, org, group, userId, with the exception of user. Instead specific user details should be their own header, i.e. where you had user.email in updateContacts, you would just have an email header in the CSV.

examples

type, org, group, userId, email, phone
'put', 'an-org', 'a-group', 'user12345', 'foo@bar.com', '555-555-5555'
'del', 'an-org', 'a-group', 'user54321'

usage

curl --location --request POST 'localhost:3000/v1/upload/cakemail/bulkLoad' \
--header 'Authorization: Bearer eyJhbGciOiJ................aTkFPoBILtrqdskosCE' \
--form 'file=@/home/austin/dev/kappa-cake/cake-email/test/bulk.csv'

updateSegment

To be added

GET /v1/read/cakemail

The read endpoint will stream a list of contacts based on options attached to the body of the request. The following options are supported.

• gt: lexicographically greater than a certain string/key
• gte: lexicographically greater or equal to a certain string/key
• lt: lexicographically less than a certain string/key
• lte: lexicographically less than or equal to a certain string/key
• limit: a number indicating how many results to return
• live: keep the stream open and send me updates to contacts as they are added to the database

These options can be combined to limit the returned contacts. It should be noted that when searching for a specific key, the key is comprised of the organization name, the group/list name, and the userId, separated by exclamation points. This allows for some powerful queries.

example

// return all contacts on ALL lists for an entire organization (full
export)
{
    "gte": "!some-org-name!",
    "lt":  "!some-org-name!~"
}

// return all contact on a particular list of an organization
{
    "gte": "!some-org-name!active",
    "lt":  "!some-org-name!active!~"
}

// return the first 50 contacts from an organization's list
// good for paginating results
{
    "gte": "!some-org-name!active",
    "lt":  "!some-org-name!active!~"
    "limit": 50
}

usage

curl --location --request GET 'localhost:3000/v1/read/cakemail' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGci.................TkFPoBILtrqdskosCE' \
--data-raw '{
	"gte": "!austins-crew!",
	"lt": "!austins-crew!~"
}'

GET /v1/get/cakemail?key=

The get endpoint return an individual contact's information by supplying a key value as a query parameter. It should be in the form of organization name, list name, and userId seperated by exclamation points and URL encoded.

A key of !austins-crew!active!bn0bv0r when URL encoded would end up as %21austins-crew%21active%21bn0bv0r

usage

curl --location --request GET 'localhost:3000/v1/get/cakemail?key=%21austins-crew%21active%21bn0bv0r' \
--header 'Authorization: Bearer eyJhbGciOiJ...............BILtrqdskosCE'