I have a api that is used to query if a job should run based on status of other jobs. This is for supporting jobs that run at a certain fixed frequency (Hourly/Daily/Weekly). The frequency of each job and status of each run is stored in a database. The API has 3 endpoints that i have listed below along with a use case
Use Case:
Assume J1 and J2 are 2 hourly jobs and J2 can run only after a successful J1 completion. All timestamps are in UTC
- GET /getSucceededTimestamps/J1?limit=3
returns up to 3 last successful timestamps as a json list ex [“2018-01-28 01:00:00”, “2018-01-28 02:00:00”] If no successful timestamps exists it returns a empty json list “[]”. The return codes are 200 in both cases. This call is idempotent
- POST /getTimestampToProcess/J2?limit=3&lookback=24H&dependecy=J1&dependency_beg_offset=0H&dependency_end_offset=0H
since J1 depends on J2 in this case the call returns the timestamps that J2 has to run for as a json array [“2018-01-28 01:00:00”, “2018-01-28 01:00:00”]. If J1 was not successful, the call would have returned an empty json list “[]”. The POST does not have a body, The return codes are 200 in both cases. This call is not idempotent. The database is now marked with a processing status for the 2 timestamps returned. A second call would return a empty json list until the status is updated to success/fail
- PUT /setstatus/J2?status=success data={“timestamps” : [“2018-01-28 01:00:00”, “2018-01-28 02:00:00”]}
This call returns updates the status to success for J2 for the 2 timestamps. Returns HTTP 204 (no content)
I get a few “it is not RESTful” remarks,
-
The POST should not have a long query string but a body. When the status is updated/created to processing in the backend the POST should return a URI. - My reasoning is that the query parameters do not go into the database, they are used to search for timestamps in the database that the job can process. So they need not be in the body of the request. The returned value is just a list of timestamps and they do not have a resource associated with them, so I don’t return a URI but just the timestamps.
-
The POST should return a error code when there is nothing to process because nothing was changed in the backend, and HTTP 201 create when there is something to be run - My reasoning is that, there is nothing to run so return a empty list, the record added to the DB has no associated resource, it is the output of the the search process based on dependency, so HTTP 200 is sufficient
Please let me know your thoughts on the Restfulness of the API (I think it is pragmatic - but would refer to the gurus opinion), the idea is just have a few endpoints for simple dependency management and status tracking.
Aucun commentaire:
Enregistrer un commentaire