Skip to content

restful api implementation

Jump to bottom
Achira-Oulu edited this page May 16, 2023 · 60 revisions

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 resourcess. Each resource should include its URL, a short description and supported methods. You should mark also which is the name of the class implementing the resource (if you have implemented such resource) 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.

✏️ 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
RecipientList v1/notification/email/recipient Returns a list of all subscribed recipients and adds a recipient to the list GET, POST YES
RecipientItem v1/notification/email/recipient/{recipientID} Adding/Updating/Deleting a recipient to/on/from the list GET, PATCH, DELETE YES
TemplateList v1/notification/email/template/ Returns a list of all saved templates and adds a template to the list GET, POST YES
TemplateItem v1/notification/email/template/{templateID} Adding/Updating/Deleting a template to/on/from the list GET, PATCH, DELETE YES
Notification v1/notification/email/push-notification Sending an email to subscribers POST YES
EmailAuditList v1/notification/email/push-notification Getting all email audits GET, POST YES

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.
Do not forget to include in the README.md file which is the path to access to your application remotely.

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.

✏️ You do not need to write anything in this section, just complete the implementation.

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.

✏️ Most important part of this section is completing the implementation. Write down here a short reflection on which are the main errors you have solved thanks to the functional tests.

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, Statelessness. Provide examples (e.g. how does each HTTP method work in your API). Note that Connectedness will be addressed in more depth in Deadline 4.

✏️ Write your text here

Addressability - All the resources in this email notification API can be reached through a unique identifier. As an example, the "getRecipientById" resource has an endpoint to get recipient data by providing a unique recipient_id.

Similarly, all the other resources are addressable through a unique identifier.

  1. Template - using a unique address, API provides facilities to delete edit, and view template data
  1. Notification - using a unique address, API provides facilities to send emails, get all email audits and get email audits by subject
  1. Recipient - using a unique request, API provides facilities to delete edit, and view recipient data

Uniform Interface - The guiding principle is to implement actions according to HTTP standards and use HTTP methods for those actions. For this we have used HTTP GET, POST, PUT, and DELETE methods. Also, all the requests and responses are using the JSON format.

For example, the recipient list resource (v1/notification/email/recipient) endpoint contains GET/POST/DELETE/PATCH methods implemented in order to view, add, edit, and delete single recipient data.

  1. GET

    • Used to return a single recipient by ID
    • Used to return all the recipients on the list

  2. POST

    • Used to add a new recipient to the list

  3. Delete

    • Used to delete a recipient from the list

  4. Patch

    • Used to update recipients on the list.

Similarly, The other resources involved with Notification & Template data have also been implemented following these standards.

Statelessness - is a principle that emphasizes the avoidance of storing client session data on the server side. In our case, The server does not store any state regarding the client session on the server side in accordance with the REST (REpresentational "State" Transfer) architecture. This limitation is known as statelessness.

We have adopted an approach where we do not store authentication details on the client side. Instead, we use a lambda function from the infrastructure: AWS Lambda, which is an event-driven serverless computing platform provided as a service of Amazon Web Services(AWS). Each Lambda function is invoked in isolation and has no knowledge of previous or future invocations, which makes it stateless and secure. Any state that needs to be maintained across invocations can be stored in external data storage services such as Amazon S3, DynamoDB, etc.

For example, only an admin, who possesses an admin key, has the authority to perform actions such as retrieving the entire recipient list, adding a recipient, deleting a recipient, and editing recipient details. It is necessary to include the admin token in the header of each API call to perform these actions.

On the other hand, other employees can only view their own data by utilizing their authentication token. Non-admin users are not granted access to view the employee list or perform actions such as creating or deleting an employee.

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.

✏️ Write your text here

URL converters, also known as parameter serializers or query string builders, play an important role in APIs. They are essential tools for generating and manipulating URLs with dynamic parameters, making API requests more flexible and versatile

The framework provides URL Converters as a practical method of converting string parameters in URLs to JavaScript objects. To prevent repeating the process of collecting the objects from the database in the method body, we have used a couple of URL converters.

Parameter Description Example Converter
{RecipientID} ID of the Recipient 001 Recipient Converter
{TemplateID} ID of the Template 001 Template Converter

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.

✏️ Write your text here For this project, we have mainly used 3 Schema validations implemented.

Recipient schema

  • Schema validation for this is performed on POST operations.
  • recipient_id,recipient_name,email_addresses,active,created_date,modified_date are required fields while recipient_id is the primary key

Template schema

  • Schema validation for this is performed on POST operations.
  • template_id,template_name,template_body,active,created_date,modified_date,'template subject' are required fields while template_id is the primary key

Email notification audit schema

  • 'email_notification_audit_id','email_subject','request_id','created_date','modified_date' are required fields while 'recipient_id'.'template_id' are nullable fields. The primary key here is email_notification_audit_id.

As an example, the template data is validated as follows:

const schemaDefinition = {
  type: 'object',
  properties: {
    applicationName: {
      type: 'string',
      minLength: 1,
      maxLength: 40,
      pattern: '^([a-zA-Z])[a-zA-Z0-9-_]*$',
    },
    emailCategory: {
      type: 'string',
      minLength: 1,
      maxLength: 40,
      pattern: '^([a-zA-Z])[a-zA-Z0-9-_]*$',
    },
    template: {
      type: 'string',
      minLength: 1,
      pattern: '^([a-zA-Z])[a-zA-Z0-9-_]*$',
    },
    templateData: {
      type: 'object',
    },
    toAddresses: {
      type: 'array',
      minItems: 1,
      items: { format: 'email', type: 'string', isNotEmpty: true },
    },
    ccAddresses: {
      type: 'array',
      items: { format: 'email', type: 'string', isNotEmpty: true },
    },
    bccAddresses: {
      type: 'array',
      items: { format: 'email', type: 'string', isNotEmpty: true },
    },
    templateId: {
      type: 'number',
    },
    recipientId: {
      type: 'number',
    },
  },
  required: [
    'applicationName',
    'emailCategory',
    'templateData',
  ],
  additionalProperties: false,
};

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.

✏️ Write your text here

This API has leveraged the infrastructure of AWS Lambda for caching purposes, which means that we have not implemented any caching mechanism within the API itself. By utilizing AWS Lambda's caching capabilities, we are able to improve the performance and efficiency of our API without having to build and maintain our own caching system.

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.

✏️ Write your text here

Authentication refers to the process of verifying the identity of a user before granting access to resources. In this case, AWS Cognito service is used as the authentication provider, with predefined identity and user pools used to manage user access.

To authenticate a user, the client must send their credentials to the server, which will verify them with AWS Cognito. If the credentials are valid, the server will authorize that the client can use to access resources.

Resources allocation

Task Student Estimated time
Design and implementation Kavindu Ravishan 5 hours
RESTful API design Windula Kularatne 10 hours
implementation & Wiki Achira Hendalage 20 hours
Implementation Sameera Gamage 5 hours
Discussion Everybody 5 hours

Report index

Clone this wiki locally