From 414a53e33ebc66317025422f1f4052a1b6cff524 Mon Sep 17 00:00:00 2001 From: jonas-martinez Date: Wed, 1 Mar 2023 14:01:47 +0100 Subject: [PATCH 1/2] docs: Crons --- src/markdown/features/crons.md | 70 ++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 src/markdown/features/crons.md diff --git a/src/markdown/features/crons.md b/src/markdown/features/crons.md new file mode 100644 index 0000000..9293f6a --- /dev/null +++ b/src/markdown/features/crons.md @@ -0,0 +1,70 @@ +Crons on Lenra are a way to schedule tasks to be executed at specific times. A cron can be created using the CRUD operations available on the following endpoints: + +- [Create](#create) (`POST /app/crons`) +- [Read](#read) (`GET /app/crons`) +- [Update](#update) (`PUT /app/crons/:name`) +- [Delete](#delete) (`DELETE /app/crons/:name`) + +## Create + + + +To create a cron on Lenra, make a POST request to the `/app/crons` endpoint with the following required parameters: + +- `listener_name`: a string corresponding to the name of the listener on the application. +- `schedule`: a string corresponding to the cron 5 star format `* * * * *`. + +You can also pass props to the request body for additional data that will be sent to the listener, for example: + +```json +{ + "listener_name": "myListener", + "schedule": "0 0 * * *", + "props": { + "userId": "1234" + } +} +``` + +The response will contain the created cron with the additional generated name parameter: + +```json +{ + "name": "5c18337c4de4a4a60ce4a6ee", + "listener_name": "myListener", + "schedule": "0 0 * * *", + "props": { + "userId": "1234" + } +} +``` + +## Read + + + +To read all the crons on Lenra, make a GET request to the `/app/crons` endpoint. The response will contain an array of all the existing crons. + +## Update + + + +To update a cron on Lenra, make a PUT request to the `/crons/:name` endpoint with the name parameter corresponding to the name of the cron to update. You can also pass the `listener_name`, `schedule`, and `props` parameters to update. + +```json +{ + "listener_name": "myUpdatedListener", + "schedule": "0 12 * * *", + "props": { + "userId": "5678" + } +} +``` + +The response will contain the updated cron. + +## Delete + + + +To delete a cron on Lenra, make a DELETE request to the `/crons/:name` endpoint with the name parameter corresponding to the name of the cron to delete. The response will contain the deleted cron. \ No newline at end of file From 84e0ed926f4aac1f481cd914df7ab598302a5119 Mon Sep 17 00:00:00 2001 From: jonas-martinez Date: Thu, 2 Mar 2023 20:58:58 +0100 Subject: [PATCH 2/2] Rework the doc for crons --- src/markdown/features/crons.md | 70 +++++++++++++++------------------- 1 file changed, 30 insertions(+), 40 deletions(-) diff --git a/src/markdown/features/crons.md b/src/markdown/features/crons.md index 9293f6a..dfaef39 100644 --- a/src/markdown/features/crons.md +++ b/src/markdown/features/crons.md @@ -1,25 +1,43 @@ -Crons on Lenra are a way to schedule tasks to be executed at specific times. A cron can be created using the CRUD operations available on the following endpoints: +Crons on Lenra are a way to schedule tasks to be executed at specific times. A cron can be managed using the CRUD operations. -- [Create](#create) (`POST /app/crons`) -- [Read](#read) (`GET /app/crons`) -- [Update](#update) (`PUT /app/crons/:name`) -- [Delete](#delete) (`DELETE /app/crons/:name`) - -## Create - - +## Creating a cron that runs each minute To create a cron on Lenra, make a POST request to the `/app/crons` endpoint with the following required parameters: - `listener_name`: a string corresponding to the name of the listener on the application. - `schedule`: a string corresponding to the cron 5 star format `* * * * *`. +The `schedule` parameter consists of five fields, each separated by a space, that represent minute, hour, day of the month, month, and day of the week. Here is the format: + +```scss +* * * * * +- - - - - +| | | | | +| | | | +----- day of the week (0 - 6) (Sunday=0) +| | | +------- month (1 - 12) +| | +--------- day of the month (1 - 31) +| +----------- hour (0 - 23) ++------------- min (0 - 59) +``` + +Each field can take the following values: + +- An asterisk (`*`) means "any value". For example, `* * * * *` would run the job every minute, every hour, every day of the month, every month, and every day of the week. + +- A single value specifies a specific value for that field. For example, `0 * * * *` would run the job at the beginning of every hour, and `0 0 1 * *` would run the job at midnight on the first day of every month. + +- A range of values specifies a range for that field. For example, `0 9-17 * * *` would run the job every minute between 9 AM and 5 PM. + +- A list of values specifies a list of values for that field. For example, `0 0 1,15 * *` would run the job at midnight on the first and fifteenth days of every month. + +- A step value specifies a value that the field must be evenly divisible by. For example, `*/15 * * * *` would run the job every 15 minutes, and `0 0 */2 * *` would run the job every other day. + You can also pass props to the request body for additional data that will be sent to the listener, for example: ```json { "listener_name": "myListener", - "schedule": "0 0 * * *", + "schedule": "* * * * *", "props": { "userId": "1234" } @@ -32,39 +50,11 @@ The response will contain the created cron with the additional generated name pa { "name": "5c18337c4de4a4a60ce4a6ee", "listener_name": "myListener", - "schedule": "0 0 * * *", + "schedule": "* * * * *", "props": { "userId": "1234" } } ``` -## Read - - - -To read all the crons on Lenra, make a GET request to the `/app/crons` endpoint. The response will contain an array of all the existing crons. - -## Update - - - -To update a cron on Lenra, make a PUT request to the `/crons/:name` endpoint with the name parameter corresponding to the name of the cron to update. You can also pass the `listener_name`, `schedule`, and `props` parameters to update. - -```json -{ - "listener_name": "myUpdatedListener", - "schedule": "0 12 * * *", - "props": { - "userId": "5678" - } -} -``` - -The response will contain the updated cron. - -## Delete - - - -To delete a cron on Lenra, make a DELETE request to the `/crons/:name` endpoint with the name parameter corresponding to the name of the cron to delete. The response will contain the deleted cron. \ No newline at end of file +You will need to remember this `name` to properly call the `UPDATE` and `DELETE` endpoints that are under `/crons/:name`.