These standards are an extension of GreatIdeaz coding standards specific to APIs. For more GreatIdeaz standards, please refer to this category.
Structure
This is the structure that should be used when creating a trellispark API. It is intended to make adding new API endpoints and controllers as simple as possible. An existing API endpoint can be copied and have only small adjustments made to be ready to perform new functions.
Note: All checks should have error handling and a return case.
- All trellispark APIs should have a single entry point called “CallAPI”.
- The single entry point should reference a method called “Call” that accepts a single parameter called “Payload”.
- The first operation should always be checking the IDatabase is initialized.
- The second operation should always be verifying the model state of the payload.
- The third operation should always be connecting to the database and validating the session.
- Once the first 3 operations are completed, the logic for the API can be performed. This logic should not be contained in the API controller. Instead there should be a class that contains the API logic.
- The logic block should only contain 1 method call. If the API is used for multiple functions, the command should be disambiguated in the logic class, not the API controller.
- Any logic that calls our SaveInstance() function should set the argument skipActions = true. If you don’t do this then there is a chance that you can introduce an infinite save loop depending how the command in your API is being called.
Returns
These standards govern the responses that the API can return. It should only every return one of the following 3 responses.
- If there is an error with the API logic, return OK with the Payload object.
- If there is an error with the database connection, return a 500 status code.
- If the model state is invalid, return a “bad request” response.
