define resource paths

[JohnRDOrazio]

We now have routing in place. We need to define a clear resource path strategy.

Current situation

Currently we have the following working paths:

1. /api/dev/: will generate a calendar, whether General Roman, or a national calendar, or a diocesan calendar, based on params
2. /api/dev/metadata/: will generate the index of all the available calendars and related data
3. /api/dev/testsindex/: will generate the index of all available unit tests
4. /api/dev/allevents/: will generate a collection of all possible liturgical events that go to creating a given calendar (this is NOT the calendar, only the events that may be found in the calendar)
5. /api/dev/regionaldata/: will produce the data for a given national or diocesan calendar, that is used to generate the calendar; can also create new data / update existing data with PUT / PATCH requests
6. /api/dev/easter/: will generate all the dates of Easter from 1583 to 9999

New Path schema

Proposed schema moving forward (RFC):

N.B. for the purposes of this API, GET and POST methods are considered equivalent, they will both simply retrieve data, the first through query parameters and the second through the body of the request (which can in turn generally have a Content-Type of either application/x-www-form-urlencoded, application/json, or application/yml)

A green checkmark :heavy_check_mark: will be placed next to the routes that have been implemented in the temporary v9 branch; those that are a work in progress will have a red exclamation point :heavy_exclamation_mark:

Calendars (GET, POST) :heavy_check_mark:

This is the true perpetual calendar endpoint, it will retrieve the actual calculated liturgical calendar for a given year

1. /api/dev/calendars/: will generate the index of all the available calendars and related data
2. /api/dev/calendar/{YEAR}/: will generate the General Roman Calendar (aka Universal) for the year {YEAR} (if year is omitted, will default to the current year)
3. /api/dev/calendar/nation/{NATION}/{YEAR}/: will generate the national calendar for {NATION} for the year {YEAR} (if year is omitted, will default to the current year)
4. /api/dev/calendar/diocese/{DIOCESE}/{YEAR}/: will generate the diocesan calendar for {DIOCESE} for the year {YEAR} (if year is omitted, will default to the current year)

TODO: consider the possibility of adding other rites, such as the Ambrosian rite or Eastern Catholic rites such as Ruthenian or Melchite / Greek Catholic... How to handle these on the path? We would need a fuller understanding of how different the calendars are compared to the Roman Rite, for example do they follow the Gregorian date of Easter or the Julian date of Easter; are they adaptable at a local level; etc.

Roman Missals (GET, POST, PUT, PATCH, DELETE) :heavy_exclamation_mark:

5. /api/dev/missals/: will get the index of all Roman Missals for which data has been defined in the API
6. /api/dev/missal/{YEAR}: will get / update / create / delete sanctorale data for the Latin Roman Missal published in the year {YEAR} (if {YEAR} is omitted will get an array of all Latin Roman Missals published since 1969)
7. /api/dev/missal/nation/{NATION}/{YEAR}: will get / update / create / delete sanctorale data for the Missal of the nation {NATION} published in the year {YEAR} (if {YEAR} is omitted will get an array of all Missals for the given {NATION} published since 1969)

Decrees of the Congregation for Divine Worship (GET, POST, PUT, PATCH, DELETE) :heavy_exclamation_mark:

8. /api/dev/decrees/: will get the data of Decrees of the Congregation for Divine Worship that add new festivities, or resolve coincidences between festivities; or create a new decree if one is issued (we shouldn't really have to update anything, but let's say a mistake was made when creating a new decree, perhaps we can allow to PATCH it; DELETE shouldn't really be needed here)

Calendar data (GET, POST, PUT, PATCH, DELETE) :heavy_check_mark:

This is data that goes to generating a National or Diocesan calendar, that cannot be handled in the Missals data; generally consists of particular operations, or liturgical events that have had changes since a Missal was published...

9. /api/dev/data/: will get the index of all data files that have been defined for national or diocesan calendars
10. /api/dev/data/nation/{NATION}/: will get / update / create / delete the data that is used to generate the national calendar for {NATION} (only data that will modify the sanctorale data from the relative Missal for the nation, or add new festivities for a given year that were not in the Missal, or move festivities etc.)
11. /api/dev/data/diocese/{DIOCESE}: will get / update / create / delete the data that is used to generate the diocesan calendar for {DIOCESE}
12. /api/dev/data/widerregion/{WIDERREGION}: will get / update / create / delete the data that is used for the Wider Region that certain nations may belong to (e.g. "Europe" or "Americas"; this data will be included in the generation of a national calendar that belongs to the given Wider Region)

N.B. As regards DELETE requests:

• {WIDERREGION} data cannot be deleted as long as there are National calendars that depend on it
• {NATION} data cannot be deleted as long as there are Diocesan calendars that depend on it.

Dates of Easter (GET, POST) :heavy_check_mark:

13. /api/dev/easter/: will generate all the dates of Easter from 1583 to 9999

Liturgical events (GET, POST) :heavy_check_mark:

14. /api/dev/events/: will generate a collection of all possible liturgical events that go to creating the General Roman Calendar, whatever the year
15. /api/dev/events/nation/{NATION}/: will generate a collection of all possible liturgical events that go to creating the national calendar for {NATION}, whatever the year
16. /api/dev/events/diocese/{DIOCESE}: will generate a collection of all possible liturgical events that go to creating the diocesan calendar for {DIOCESE}, whatever the year

Unit Tests (GET, POST, PUT, PATCH, DELETE) :heavy_check_mark:

17. /api/dev/tests/: will generate the index of all available unit tests
18. /api/dev/test/{TEST}/: will get an existing test by ID, or create a new test / update / delete an existing test by ID

Please feel free to ask questions or contribute with ideas for better resource paths!