restful api implementation - LassiHeikkila/taskey GitHub Wiki

Important information for Deadline 3

‼️  This chapter should be completed by Deadline 3 (see course information at Lovelace)


πŸ“‘  Chapter summary In this section you must implement a RESTful API. The minimum requirements are summarized in the Minimum Requirements section of the Project Work Assignment. If you do not meet the minimum requirements this section WILL NOT be evaluated.

CHAPTER GOALS

  • Implement a RESTful API
  • Write tests for the API

βœ”οΈ     Chapter evaluation (max 20 points) You can get a maximum of 20 points after completing this section. More detailed evaluation is provided in the evaluation sheet in Lovelace.

RESTful API implementation

List of implemented resources

πŸ“‘  Content that must be included in the section A list of all implemented resources. Consider that you do not need to implement every resource you initially planned.   The minimum requirements are summarized in the Minimum requirements section from the Project work assignment. Do not forget to include in the README.md file which is the path to access to your application remotely.

✏️ List your resources here. You can use the table below for listing resources. You can also list unimplemented resources if you think they are worth mentioning

Resource name Resource url Resource description Supported Methods Implemented
Organization /api/v1/organizations/{organization_id}/ GET, PUT, DELETE Yes
UserCollection /api/v1/{organization_id}/users/ GET, POST Yes
User /api/v1/{organization_id}/users/{user_id}/ GET, PUT, DELETE Yes
UserToken /api/v1/{organization_id}/users/{user_id}/tokens/ Create access token POST Yes
MachineCollection /api/v1/{organization_id}/machines/ GET, POST Yes
Machine /api/v1/{organization_id}/machines/{machine_id}/ GET, PUT, DELETE Yes
MachineToken /api/v1/{organization_id}/machines/{machine_id}/tokens/ Create access token POST Yes
Schedule /api/v1/{organization_id}/machines/{machine_id}/schedule/ Manage machine schedule GET, POST, PUT, DELETE Yes
Task /api/v1/{organization_id}/tasks/{task_id}/ GET, PUT, DELETE Yes
TaskCollection /api/v1/{organization_id}/tasks/ GET, POST Yes
Record /api/v1/{organization_id}/machines/{machine_id}/records/{record_id}/ GET, DELETE Partially
RecordCollection /api/v1/{organization_id}/machines/{machine_id}/records/ View and create records GET, POST Partially

Basic implementation

πŸ’»     TODO: SOFTWARE TO DELIVER IN THIS SECTION The code repository must contain:
  1. The source code for the RESTful API 
  2. The external libraries that you have used
  3. We recommend to include a set of scripts to setup and run your server
  4. A database file or the necessary files and scripts to automatically populate your database.
  5. A README.md file containing:
    • Dependencies (external libraries)
    • How to setup the framework.
    • How to populate and setup the database.
    • How to setup (e.g. modifying any configuration files) and run your RESTful API.
    • The URL to access your API (usually nameofapplication/api/version/)=> the path to your application.
NOTE: Your code MUST be clearly documented. For each public method/function you must provide: a short description of the method, input parameters, output parameters, exceptions (when the application can fail and how to handle such fail).  In addition should be clear which is the code you have implemented yourself and which is the code that you have borrowed from other sources. Always provide a link to the original source. This includes links to the course material.

Source code
API
Especially interesting:


RESTful API testing

πŸ’»     TODO: SOFTWARE TO DELIVER IN THIS SECTION The code repository must contain:
  1. The code to test your RESTful API (Functional test)
    • The code of the test MUST be commented indicating what you are going to test in each test case.
    • The test must include values that force error messages
  2. The external libraries that you have used
  3. We recommend to include a set of scripts to execute your tests.
  4. A database file or the necessary files and scripts to automatically populate your database.
  5. A README.md file containing:
    • Dependencies (external libraries)
    • Instructions on how to run the different tests for your application.
Do not forget to include in the README.md the instructions on how to run your tests. Discuss briefly which were the main errors that you detected thanks to the functional testing.

Remember that you MUST implement a functional testing suite. A detailed description of the input / output in the a REST client plugin.

In this section it is your responsibility that your API handles requests correctly. All of the supported methods for each resource should work. You also need to show that invalid requests are properly handled, and that the response codes are correct in each situation.


Tests are run by a Github Actions workflow, so results can be viewed here: -> Go
Coverage is quite low at the moment. Definitely more tests, especially non-happy-path tests are needed.


REST conformance

πŸ“‘  Content that must be included in the section Explain briefly how your API meets REST principles. Focus specially in these three principles: Addressability, Uniform interface, and Statelessness. Provide examples (e.g. how does each HTTP method work in your API). Note that Connectedness will be addressed in Deadline 4.

Each endpoint is stateless. No knowledge of previous requests are used when processing a request.

Each resource is uniquely addressable by a combination of identifiers.

Interface is quite uniform and makes logical sense (in authors personal opinion).
HTTP verbs match with the actions performed based on the requests.
API is CRUD style, so POST => Create, GET => Read, PUT => Update, DELETE => Delete.


Extras

πŸ“‘  Details on extra features This section lists the additional features that will be graded as part of the API but are not required. In addition to implementing the feature you are also asked to write a short description for each.

URL Converters

πŸ“‘  Fill this section if you used URL converters Write a short rationale of how URL converters are used, including your thoughts on the possible trade-offs. Go through all URL parameters in your API and describe whether they use a converter, what property is used for converting, or why it's not using a converter.

No URL converters implemented. Endpoints use variables in the paths but they are not automatically converted.
In my opinion, URL converters are not a very good fit with github.com/gorilla/mux. It felt much more natural to use the arguments as is and do lookups when needed.


Schema Validation

πŸ“‘  Fill this section if you used JSON schema validation Write a short description of your JSON schemas, including key decision making for choosing how to validate each field.

No schema validation at this time. Definitely should be added later, just running short on time.

Only "schema validation" done is to check that record ID is an integer.


Caching

πŸ“‘  Fill this section if you implemented server side caching Explain your caching decisions here. Include an explanation for every GET method in your API, explaining what is cached (or why it is not cached), and how long is it cached (and why). If you are using manual cache clearing, also explain when it happens.

No caching implemented. Also not setting any cache control headers. Individual resources are small, except maybe for collections, so caching is not important for now.


Authentication

πŸ“‘  Fill this section if you implemented authentication Explain your authentication scheme here. Describe the authentication requirements for each resource in your API, and your reasoning for the decisions. In addition, provide a plan for how API keys will be distributed, even if the distribution is not currently implemented.

Every request except for a few special endpoints is authenticated.

Two authentication schemes are used, one for interactive (browser, etc.) use with Bearer tokens and one for scripted use with generated API keys.

Additionally, a role-based access control system is used where user must have a specific role to perform some actions, e.g. be administrator to DELETE a user account.


Resources allocation

Task Student Estimated time
Everything Lassi HeikkilΓ€ 60h
⚠️ **GitHub.com Fallback** ⚠️