romcal-api: A TypeScript repository from romcal

REST API to get the liturgical calendar in the Catholic Roman rite.

Usage:
- As an Express middleware
- As an AWS Lambda (through the serverless framework)
REST API:
Contribute
Roadmap

If you are looking to use romcal as a Node.js dependency without Express, or as a browser / front-end library, you might consider having a look to the main romcal repository instead.

Usage

→ As an Express middleware

Actually only Express is supported. More frameworks might be supported in the future.

$ npm install romcal-api
$ npm install express

// index.js

const express = require('express');
const romcalConfig = { baseUrl: '' }; // Optional config
const romcalMiddleware = require('romcal-api').expressMiddleware(romcalConfig);

const app = express();
const PORT = process.env.PORT || 3000;

app.use(romcalMiddleware);

app.listen(PORT, () => {
  console.log(`romcal API running on port ${PORT}`);
});

$ node index.js

→ As an AWS Lambda (through the serverless framework)

Actually only AWS Lambda is supported.

To get started, you'll need the Serverless Framework installed. You'll also need your environment configured with AWS credentials. The steps below just gives minimal information to setup romcal-api quickly. To get help, or get the complete configuration instructions, you will find a lot more knowledge and support over internet and particularly from the serverless.com website.

First, create a new working directory for your romcal API project:

# Create a new Serverless service/project
$ serverless

# Change into the newly created directory
$ cd my-romcal-api

Then, install romcal-api:

$ npm install romcal-api

With romcal-api installed, add the application code in the handler.js:

// handler.js

const romcalAPI = require('romcal-api');
module.exports.romcalHandler = romcalAPI.handler;

Sample settings and romcal function to add in the serverless.yml:

# serverless.yml

provider:
  name: aws
  runtime: nodejs12.x

functions:
  romcal:
    handler: handler.romcalHandler
    events:
      - http: ANY /
      - http: 'ANY {proxy+}'

When everything is set up, romcal-api is ready to be deployed:

$ sls deploy

REST API

Rest API are documented here: romcal.github.io/romcal-api/. You can use tools like Postman to play with the API.

Below a list of the available APIs. Click on the corresponding links for more informations.

Celebrations

→ For a specific year, month or date

Get the calendars over a whole year (civil or liturgical), or for a specific month or a date within a year.
GET /calendars/:name/:locale?/:year?/:month?/:day?

→ For yesterday

Get all the calendars that took place yesterday.
GET /calendars/:name/:locale/yesterday

→ For today

Get all the calendars taking place today.
GET /calendars/:name/:locale/today

→ For tomorrow

Get all the calendars that will take place tomorrow.
GET /calendars/:name/:locale/tomorrow

→ For a specific liturgical period or season

Get a collection of calendars that match the specified liturgical period. The period is generally a season or a an octave.
GET /calendars/:name/:locale/:year/period/:period
The available period key names are:

Official liturgical seasons: advent, christmastide, ordinary-time, lent, easter-triduum, eastertide.

Official liturgical periods and octaves: christmas-octave, holy-week, easter-octave.

Other periods, for convenient usage only: early-ordinary-time, later-ordinary-time.

→ Lookup from a celebration

This feature is not fully supported yet. The endpoint will lookup for a liturgical celebration (defined by its key name), and will return all the calendars that occur for this liturgical date (within the given year). The celebration with the provided key name may not be output if this celebration has been replaced by another celebration with a higher rank. If the celebration key name doesn't exist in romcal for a particular calendar, it will return an error.
GET /calendars/:name/:locale/:year/lookup/:lookup

Calendars

→ List all calendars

List the name of all calendars available from romcal.
GET /calendars

Locales

→ List all supported locales

Get the locale codes of all supported locales by romcal.
GET /locales

Version

→ Get API version

Get the version of romcal and romcal-api.
GET /version

Contribute: make romcal-api better

romcal-api is in the early stages of development: the API and returned schemas could change in a near future. Any help, or simply sharing ideas on the issue tracker, are all welcome!

→ Get the romcal-api project

$ git clone https://github.com/romcal/romcal-api.git
$ cd romcal-api
$ npm install

Note: if you plan to submit Pull Requests, first you must fork this project in your own GitHub profile, and then clone your forked romcal-api repository.

→ Run and debug romcal-api locally

Run an Express server with a watcher. The server is reloaded each time you edit the code.

$ npm start

Or if you have Serverless installed on your machine, you can start romcal-api locally in an AWS λ and API Gateway emulator:

$ npm run offline

→ Run tests

Execute tests once:

$ npm test

Or run a test watcher:

$ npm run test:watch

→ Build sources

Builds all the TypeScript sources to JavaScript, allowing importing the romcal-api module in any Node.js projects:

$ npm run build

Note: this step as well as tests are run automatically before releasing a new version to npmjs.org

Roadmap (non-exclusive)

Get dates within a custom range: between 2 dates (civil or liturgical date), or 2 periods (the first day of the first period and the last day of the 2nd period)
Support GraphQL
Support date offset to manage different time zones between clients and the back-end API
Support Docker
More tests
More documentation
More examples
...

History

1.2.0 Update the Rest API (please check the documentation) & Code refactor.
1.1.0 Update romcal dependency. API change, the returned data is now an Object that contains the celebrations in a specific celebrations property. On each celebration, the moment property is renamed to date.
1.0.6 Calendar refactor and a lot of new tests added. Bug fixes.
1.0.5 Add new calendar tests and fix bugs. Fix the nodemon debug mode.
1.0.4 Add 404 error message on "Not found pages".
1.0.3 Get romcal-api version from the API. Support optional parameters when using romcal-api through an Express middleware.
1.0.2 Readme fine-tuning.
1.0.1 New logo for romcal-api.
1.0.0 Bump version. After initial commits to make romcal-api alive, this project is now enough tooled and stable to be used as third party app or server.
0.1.8 Introduce test framework: Jest and Supertest. Starting to stabilize the code and consolidate returned data.
0.1.7 Update build files. Update this readme.md
0.1.6 Start a calendar endpoint refactor.
0.1.5 The access point to list all supported locales now output real data from romcal.
0.1.4 Add .npmignore file, and rename some files correctly to lowercase.
0.1.3 Introduce the serverless framework into romcal-api: romcal-api is now available as a wrapped Express middleware or a FaaS/Lambda.
0.1.2 Update node dependencies and use the last version of romcal 1.3.0
0.1.1 Initial API setup and documentation

License

MIT