RESTTful API description - shanz007/IceHockeyTrackerAPI GitHub Wiki
📑 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
Describe the API you are going to implement. Also describe the larger imaginary architecture that would exist around that API - while you do not need to implement these other components, they will be helpful in imagining context for your API. Your API will be a component that stores, and offers an interface to, some important data in the larger ecosystem. Think about a larger system, and then take out one key piece to examine - this will be your API.
Describe the API briefly and comment what is the main functionality that it exposes. Focus in the API not in any specific application that is using this API. Take into account that in the end, a WEB API is an encapsulated functionality as well as the interface to access that functionality. Remember that your API is just one part of a larger machine. It does not need to do everything. There will be other components in the system to do those things. This course focuses on creating a small API in detail - thinking too big from the start will drown you in work later.
A really short version of an overview for 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[...]“
✏️
The IceHockeyTracker Web API serves as a critical sub-component within the team management component of a larger sports administration system, which typically covers all the aspects of sports administration areas like user, team, event, facility, payment, etc. The main focus is to aid directly or indirectly in decision-making for management staff regarding various matters related to player, coach, and team selections, improvements, budget planning, scheduling, etc.
This sub-component allows sports administrators or sponsors to track and manage league teams more effectively by utilizing tournament statistics, feedback, and rankings exposed via a set of beneficial APIs.
The API provides access to players', coaches, and managers personal data, as well as tournament-related data. This information can be consumed by other components of the administration system with appropriate security levels, ensuring that access is permitted only upon providing access tokens to maintain the criticality and security of the data.
The main sports administration system may include components and provide the following functionalities
Sports Administration System:
Team Management: Handles Team management functionalities like creating and managing teams with rosters, assigning players, captains, and coaches, tracking, scheduling matches, and managing team aspects with feedback, tournament leagues, etc.
User Management: Handles user registration, authentication, and authorization. It allows administrators to manage user accounts, roles, and permissions.
Finance and Accounting: Handles financial-related functionalities like budgeting, invoicing, reporting, etc.
Facility Management: Handles facility-related functionalities like managing sports facilities, booking courts, maintaining equipment, etc.
Event Management: Handles event related functionalities like planning, and management of sports events like scheduling, venue selection, participant registration etc.
As per the requirements and scope of this project, focus is given on some aspects of team management & user management components are considered.
📑 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:
"The API permits users send messages. The forum contains a list of categories and a list of users. Each category specifies a name, a description and a thread. A thread is [...]The forum may contain 0 or more categories… Each category may have 0 or more threads… Users can write and read messages to a forum thread. A user has a profile, basic information, activity information (stores, for instance, all the messages sent by a user, the messages marked as favorites). [...]The user history contains information of the last 30 messages sent by the user.[…]"
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.
✏️
The IceHockeyTracker Web API facilitates decision-making processes. The main entity, User, encompasses personal details such as full name, email, date of birth, social security number, role, and rank. Users can assume one of the following role types: player, coach, manager, or administrator.
With the exception of the Administrator role, all other users receive rankings from their designated supervisors, referring to specific Ranking Rules for each user role along with corresponding scores. These scores are utilized to rank players, coaches, and managers by their supervisors. Coaches and managers, in turn, rank players and coaches. Each user has the ability to receive scores from others.
Players and coaches are associated with a team, where each team can consist of multiple players and only one coach. Furthermore, each player and coach exclusively serves one team. Contract details are maintained for every user.
All teams participate in tournament matches, and match results are recorded along with match statistics. Coaches and managers are responsible for providing feedback on each match.
The relationship among entities in the Team Management component is illustrated in the following diagram. Each component is represented in microservice architecture.
📑 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.✏️Client: API-Based Sport League Administration System
Functionality: The API-based Sport League Administration System would be implemented in such a way that sports administrators with a user-friendly interface to manage premier league data efficiently. It allows administrators to make prospective team formations by using exposed APIs.
How it Uses the Web API:
User Management: A web UI interface can interact with the User Management endpoints of the IceHockeyTracker API to create and manage premier league users. It utilizes the API to assign specific access levels to users and ensures proper authentication and authorization mechanisms are in place.
League Management: A web UI interface can utilize the League Management endpoints of the IceHockeyTracker API to store and retrieve recent tournament statistics. It accesses team details and player performance details cohesively to provide administrators with comprehensive insights into premier league data.
Manager/Sponsor Access: A web UI interface leverages the Manager API endpoints to provide managers with access to comprehensive premier league data. It enables listing of players, coaches, and tournament results from a super admin point of view, offering insights and analytics to facilitate informed decision-making in sports administration.
Service: Premier League Analytics Dashboard
Functionality: The Premier League Analytics Dashboard offers administrators and managers insights and analytics into premier league tournament data. It provides visualizations, charts, and reports on team performance, player statistics, match outcomes, and user engagement metrics.
How it Uses the Web API:
Data Retrieval: The Premier League Analytics Dashboard retrieves premier league tournament data from the IceHockeyTracker API. It accesses recent tournament statistics, team details, and player performance details to generate visualizations and reports.
Manager Insights: The dashboard utilizes the Manager API endpoints to offer managers access to comprehensive premier league data. It provides insights and analytics to facilitate informed decision-making, enabling managers to optimize team strategies and improve sports administration efficiency.
📑 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.
✏️
Following are some of the links that we have referred to in order to understand where REST-HATEOAS or hypermedia-based concepts and practical examples are being used. We also went through commercial sports-related data APIs
REST-HATEOAS or hypermedia concepts
Commercial sport related Data sites :
-
https://developer.sportradar.com/docs/read/cricket/Cricket_v2
-
https://cricket-postman.sportmonks.com/#66c4d790-d821-4834-aa77-b9b1b0d90882
The Sports Open Data API provides access to a wide range of sports-related data, including team details, player statistics, match results, and tournament information. It covers various sports, including soccer, basketball, tennis, and ice hockey, making it relevant to the context of premier league sports administration.
| Task | Student | Estimated time |
|---|---|---|
| Meetings | All | 2h |
| Repository and Wiki setup | Shanaka Badde Liyanage Don | 0.5h |
| Wiki content write up & API | Shanaka Badde Liyanage Don | 4h |
| Wiki content write up & API | Emmanuel Ikwunna | 3h |
| Wiki content write up & API | Md Mobusshar Islam | 3h |