Repository navigation
RESTTful API description
📑 Chapter summary
This chapter must provide a good overview of the Web API that your group is going to develop during the course, and some insight into the (imaginary) microservice architecture it will be a part of. You should not focus in implementation aspects such as database structure, interfaces or the request/responses formats. We recommend that you look into existing APIs (see Related work below) before writing the description for your own API.- Understand what is an API
- Describe the project topic API
- Describe how the API would be used as part of a larger architecture
✔️ Chapter evaluation (max 5 points)
You can get a maximum of 5 points after completing this Chapter. More detailed evaluation is provided in the evaluation sheet in Lovelace.📑 Content that must be included in the section
A really short version of an overview of the RESTful Web API could be:
“The discussion forum Web API offers different functionalities to structure non-real-time conversations among the people of a group about topics they are interested in certain topic. Messages are grouped in Threads, that at the same time are grouped in Topics. The messages are accessible to anyone, but posts can only be created by providing credentials of a registered user [...] This API could exist as part of an online learning environment system where it is responsible for offering discussion forum features that can be included in other components of the learning environment. For example, a programming task (managed by a different component) can include its own discussion board managed by the discussion forum API[...]“
Email notification service is an API that is vital for almost any organization or industry that communicates with a customer base. The main goal of this API is to provide a platform for the users as well as admins of an organization to communicate effectively with each other as well as examine their user data. The API comes with a web application where the users as well as admins are able to add Recipient and Template information to the database of the system. Access to the API is only provided after verifying the user credentials using an external service(AWS Cognito), after then the users are given different levels of access depending on their role(Admin/User). Some of the key components of the API and their details are as follows:
- Notifications - Allows users/admins to send notifications.
- Templates - Allows users/admins to add/delete/modify templates.
- Recipients - Allows users/admins to add/delete/modify recipients.
- Audits - Allows admins to manage the services.
In today's world, email notification APIs are becoming increasingly important as they provide a reliable and efficient way for organizations to communicate with their customers. With the rise of e-commerce and online services, this email notification service can be easily used to improve their customer experience and keep their customers informed.
Sending emails in bulk is a super helpful tool for companies and organizations. With this, they can reach lots of people at once and save time compared to sending individual emails. Not only that, but it's also a lifesaver when there's a problem with the system. Quickly getting the word out to the right people can help solve any issues faster and make sure everything is running smoothly.
This is kind of a micro service that can be used in a larger system to communicate among the users under a given template to make the information tacking easy. As an example, the university moodle email service can be implemented using this microservice to streamline the standard usage of the service as well as to handle the mailing system easily by making the process fast.
This API acts as a microservice of a larger system enabling other services in the system can consume thismicroservicee withhighh cohesion and low coupling
This service is used to send emails in bulk, including both to users and to programmers in case of system issues. The service provides the capability to send a large number of emails efficiently and effectively. The specific implementation details and guidelines for using this service are not specified.
📑 Content that must be included in the section
Define the main concepts and describe the relations among them textually. Roughly, a concept is a real-world entity that is expected to be of interest to users or other services. This section will be a guideline for choosing your resources to implement in Deadline 3. Students should remember that some of the concepts might not be a resource by themselves, but just a part of it (resource property). In this section, students should not describe the RESTful resources, but identify which are the main ideas of the API. Do not forget to include the relations among the concepts.A description of the main concepts for the Forum API could be:
"Our email service is a powerful and user-friendly tool that enables organizations to connect with their audience and increase engagement through personalized email campaigns. With its intuitive interface and flexible communication capabilities, users can easily create and manage email newsletters to suit their needs. In addition to its marketing functions, this service can also be used to send internal notifications to other services in the event of an internal system failure. This makes our email service a versatile and reliable tool for both external and internal communication."
Include a diagram which shows the relations among concepts.
This section is important because it outlines the concepts that you will later implement. In particular, the diagram defined here will follow you throughout the project report and you will be adding more details to it.
This email service is a friendly and effective tool designed to help organizations connect with their audience and drive engagement through personalized email campaigns. With its user-friendly interface and flexible communication capabilities, it's easy for users to create and manage email newsletters. This service can be also used to internally notify other services In the event of a internal system failure.
📑 Content that must be included in the section
Describe at least one client and one service that could use your Web API. You must explain here what is the functionality provided by the client/service, and how it uses the Web API to implement this functionality.✏️ Write your text here
Web Application
- The front-end react application remains the main way to interact with the API and use its functionalities
- The application allows admins to create/delete/modify templates through the app and it allows users to send emails.
- Allows admins to view all the recipient & template data.
API
-
Sending emails with templates across large crowd groups for the applications such as newsletters/invoicing/notifications etc.
-
Email marketing campaigns: You can use your API to create and send newsletters to your email subscribers for marketing campaigns.
-
News updates: Use the API to send news updates or notifications to your subscribers. For example, you could send out a daily or weekly newsletter with curated news articles.
-
Event updates: If you're running an event, you can use the API to send updates and reminders to attendees. This can include important dates, schedules, and last-minute changes.
-
Promotions and special offers: You can use the API to send out promotions and special offers to your subscribers. This can be a great way to boost sales and keep your customers engaged.
-
Internal communications: You can use the API to send internal newsletters or updates to your team. This can be a great way to keep everyone on the same page and ensure that everyone is up to date on important information.
-
Surveys and feedback: Use the API to send out surveys or feedback forms to your subscribers. This can be a great way to gather feedback from your customers and improve your products or services
📑 Content that must be included in the section
Find at least one API that resembles the functionality provided by yours. Explain in detail the functionality provided by the API. Classify the API according to its type (RPC, CRUD REST, pure REST, hypermedia driven ...) justifying your selection. Provide at least one example client that uses this API.The purpose of this task is to get more familiar with what an API is. This will be helpful in describing your own API. Therefore, it is recommended to do this section after you have decided the topic of your project but before writing your API description.
(The main operation in the API described here has some similar operations to the current services like Mailchimp. In this service, the initial task is to pick the template for the email, then adding the content that is required by the user, then select the people who are receiving this set of emails, then sending the email to the bulk receivers.
The options which have been included in the API have the same operations like, selecting or using the template, then adding the message fields, then adding the receiving audience, then sending the emails. This service which has been mentioned in the project can customize the templates too.)
✏️ The main operation in the API described here has some similar operations to the current services like Mailchimp. In this service, the initial task is to pick the template for the email, then adding the content that is required by the user, then select the people who are receiving this set of emails, then sending the email to the bulk receivers.
The options which have been included in the API have the same operations like, selecting or using the template, then adding the message fields, then adding the receiving audience, then sending the emails. This service which has been mentioned in the project can customize the templates too.
In addition to that, These email notification API s are used to send automated emails to users whenever any event occurs in an application. When the basic operations are considered, these events can include new user registrations, order confirmations, requests for password reset, new user log on or payment confirmations. Most of the operations can be done by some notification services but they are limited to those operations. For example,
SendGrid
Mailgun
Twilio SendGrid EMail API
Can be considered. SendGrid offers features like, email templates, delivery optimizations and email analytics. Mailgun has features like email validation, spam filtering, and sending bulk emails. Then Amazon SES service provides scalable services mostly business oriented. Finally the Twilio SendGrid email API is a cloud based email API and this allows the users to send and receive emails from and to their applications.
All these services are working with interfaces which are used to interact with the email service providers infrastructure. What these APIs do is make things easy and surpass any complexities of managing email servers and filtering spam emails and other user defined tasks related to email services. For example, in an E-commerce web site, if the owner wants to send an email notification to the customers about their purchases or about new products, or even a specific notification when they purchase something, an email notification service can be used to automate that process. Usually, the API service requests an account of the owner and then they provide the API key to operate the service in the web site. Then after integrating the service in the web site, the owner can automate the email service requirements in the web site. In most of the occasions, a set of back end coding should be integrated in the web site back end for these services to work.
For an example, MailGun is taken to discuss about client examples.
Here are a few examples of popular clients and libraries that can be used to interact with the Mailgun API:
cURL is a command-line tool that allows making HTTP requests. Developers can use cURL to interact with the Mailgun API directly from the command line or within scripts. Here's an example cURL command to send an email using the Mailgun API:
curl -s --user 'api:YOUR_API_KEY' \
https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
-F from='Sender Name <sender@example.com>' \
-F to='recipient@example.com' \
-F subject='Example Subject' \
-F text='Hello, this is the email content.'Mailgun provides an official Python library that simplifies the integration with the Mailgun API. Developers can install the library using pip and leverage its functions and classes to send emails, manage mailing lists, and handle other email-related tasks. Here's an example of sending an email using the Mailgun Python library.
import requests
from mailgun.api_client import Client
mg_client = Client(domain='YOUR_DOMAIN_NAME', api_key='YOUR_API_KEY')
response = mg_client.send_message(
from_email='sender@example.com',
to=['recipient@example.com'],
subject='Example Subject',
text='Hello, this is the email content.'
)
print(response.status_code)
print(response.json()) | Task | Student | Estimated time |
|---|---|---|
| Finding client example of the API & stating API uses & defining main functionalities and relationships among them | Kavindu Ravishan | 20 hours |
| Write overview and the main concept of some features, draw a simple diagram, and state some API uses | Windula Kularatne | 40 hours |
| Describe APIs to be implemented, APIs features, relationships, implications, and related work | Achira Hendalage | 25 hours |
| Writing basic overviews on different API features. Further explaining the assigned API uses, describing their functions and relationships. | Sameera Gamage | 20 hours |
| Discussion | Everybody | 20 hours |