REST API to get the liturgical calendar in the Catholic Roman rite.
Powered by romcal.
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.
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 romcalMiddleware = require('romcal-api').middleware;
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
Actually only AWS Lambda is supported. More providers might be supported in the future.
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.romcalAPI = romcalAPI.handler;
Sample settings and romcal function to add in the serverless.yml
:
# serverless.yml
provider:
name: aws
runtime: nodejs12.x
functions:
app:
handler: handler.romcalAPI
events:
- http: ANY /
- http: 'ANY {proxy+}'
When everything is set up, romcal-api is ready to be deployed:
$ sls deploy
You can use tools like Postman to play with the API.
- Get all calendars
GET /calendars
Output an Array
of calendar names, supported by romcal.
- Get all locales
GET /locales
Output an Array
of locales keys, supported by romcal.
- Get celebrations
GET /calendar/{name}/{locale}/{date}
Output an Array
of celebrations ordered by date. For all endpoints:
{name}
: represent the name of the calendar, generally a country name. For exampleitaly
. If the calendar doesn't exist, romcal will return a404 NOT FOUND
.{locale}
: represent the locale used to retrieve data. For exampleit
. If the locale doesn't exist, romcal will fall back to the defaulten
locale. However another specific endpoint is available to get the list of supported locales by romcal.{date}
(optional): scope the returned data to a specific period or date.
{date} : Get celebrations... |
Endpoint |
---|---|
For the current year: | GET /calendar/{name}/{locale} |
For a specific year: | GET /calendar/{name}/{locale}/{YYYY} |
For a specific month within a year: | GET /calendar/{name}/{locale}/{YYYY-MM} |
For a specific date: | GET /calendar/{name}/{locale}/{YYYY-MM-DD} |
For yesterday: | GET /calendar/{name}/{locale}/yesterday |
For today: | GET /calendar/{name}/{locale}/today |
For tomorrow: | GET /calendar/{name}/{locale}/tomorrow |
For a specific liturgical season within a year: The season key is described below this table. |
GET /calendar/{name}/{locale}/{YYYY-season} |
For a date that matches a given liturgical celebration within a year: The celebration-lookup is described below this table.Not fully supported yet |
GET /calendar/{name}/{locale}/{YYYY-celebration-lookup} |
The season
key name must be written in kebab case.
If the season key name doesn't exist, it will return an error (404 NOT FOUND
).
The available season key names are: advent
, christmastide
, early-ordinary-time
, lent
, easter-triduum
, easter-octave
, eastertide
, later-ordinary-time
, ordinary-time
.
The celebration-lookup
must be a celebration key name written in kebab case. 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 celebrations that occur for this liturgical date (within a specific year).
The celebration with the provided key name might not be not 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 (404 NOT FOUND
).
By default, each period is computed within a civil year (from 1 January to 31 December of the given year).
To get dates computed within a liturgical year, you need to specify calendar=liturgical
as a URL parameter.
When dates are computed within a liturgical period, year
corresponds to the year in which the liturgical year began.
/calendar/france/fr
return an array of dates from 1 January to 31 December of the current year./calendar/poland/pl?type=liturgical
return an array of date from the 1st Sunday of Advent to the last Saturday of Ordinary Time of the current liturgical year./calendar/canada/en/2018-12?type=liturgical
return an array of dates from December 2, 2018 (which is the first day of the liturgical year for 2018-2019) to December 31, 2018.
Theses optional query strings are available for filtering data directly from the server:
weekday=[int]
: Filter the results on a specific weekday.0
is Sunday,6
is Saturday. For example?weekday=0
.title=[string]
: Filter the results on a specific celebration title. The title needs to be in kebab-case. For example?title=patron-of-europe
.
You can, of course, combine different filters. For example /calendar/spain/es?weekday=4&title=martyr
group=[string]
: Calendar dates can be grouped by various criteria upon invocation like so:days
,months
,days-by-month
,weeks-by-month
,cycles
,types
,liturgical-seasons
,liturgical-colors
,psalter-weeks
.
When using this parameter, romcal-api output first an Object
where keys represent the grouped data.
If the criteria aren't recognized, romcap-api will return an error (422 UNPROCESSABLE ENTRY
).
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!
$ 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 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:
$ sls offline start
Execute tests once:
$ npm test
Or run a test watcher:
$ npm run test:watch
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
Below are a list of publicly available APIs based on this project:
- Add full API support for Calendars, Locales, Dates
- Get dates within a custom range: between 2 dates (civil or liturgical date), or 2 seasons (the first day of the first season and the last day of the 2nd season)
- Replace Express by Fastify or Koa -> they are more modern (but still very mature), highly maintained and focus on speed.
- Move to GraphQL (or support both REST API and GraphQL)
- Support date offset to manage different time zones between clients and the back-end API
- Support Docker
- More tests
- More documentation
- More examples
- ...
- 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
MIT