|| MessageBoard Api ||
___________________________
Joey Palchak | Richard Barbour | Onur Kaymak
Initiated October 25th, 2023.
Project Docs · Report Bug · Request Feature
An API that functions as a message board utilizing RESTful principles and Json web tokens (JWT) for authentication to keep the API Read-Only except for authenticated users. The user is able to see the in-use version of the API when using Postman.
- If any bugs are discovered, please contact the author(s).
- Visual Studio Code
- C#
- ASP.NET Core MVC
- MySQL 8.0.34
- Entity Framework Core 6.0.0
- Entity Framework Core CLI Tools 6.0.0
- Postman
- On macOS Mojave or later
- Click here to download the .NET Core SDK from Microsoft Corp for macOS.
- On Windows 10 x64 or later
- Click here to download the 64-bit .NET Core SDK from Microsoft Corp for Windows.
Enter the command dotnet tool install -g dotnet-script
in Terminal for macOS or PowerShell for Windows.
For Entity Framework Core, we'll use a tool called dotnet-ef to reference the project's migrations and update our database accordingly. To install this tool globally, run the following command in your terminal:
$ dotnet tool install --global dotnet-ef --version 6.0.0
Optionally, you can run the following command to verify that EF Core CLI tools are correctly installed:
$ dotnet ef
This project assumes you have MySQL Server and MySQL Workbench installed on your system. If you do not have these tools installed, follow along with the installation steps for the the necessary tools introduced in the series of lessons found here on LearnHowToProgram.
Download and install the appropriate version of MySQL Workbench.
(Optional) Download and install Postman.
To view or edit the code, you will need a code editor or text editor. A popular open-source choice for a code editor is VisualStudio Code.
- Code Editor Download:
- Click the download most applicable to your OS and system.
- Wait for download to complete, then install -- Windows will run the setup exe and macOS will drag and drop into applications.
- Optionally, create a GitHub Account
- Navigate to the MessageBoard Api repository here.
- Click 'Clone or download' to reveal the HTTPS url ending with .git and the 'Download ZIP' option.
- Open up your system Terminal or GitBash, navigate to your desktop with the command:
cd Desktop
, or whichever location suits you best. - Clone the repository to your desktop:
$ git clone https://github.com/jfpalchak/MessageBoardAPI.git
- Run the command
cd MessageBoardAPI/MessageBoardApi
to enter into the project directory. - View or Edit:
- Code Editor - Run the command
code .
to open the project in VisualStudio Code for review and editing. - Text Editor - Open by double clicking on any of the files to open in a text editor.
- Code Editor - Run the command
- Navigate to the MessageBoard Api repository here.
- Click 'Clone or download' to reveal the HTTPS url ending with .git and the 'Download ZIP' option.
- Click 'Download ZIP' and extract.
- Open by double clicking on any of the files to open in a text editor.
- Create a new file in the MessageBoardApi project directory named
appsettings.json
- Add in the following code snippet to the new
appsettings.json
file:
{
"Logging": {
"LogLevel": {
"Default": "Warning"
}
},
"AllowedHosts": "*",
"ConnectionStrings": {
"DefaultConnection": "Server=localhost;Port=3306;database=message_board;uid=[YOUR-USERNAME-HERE];pwd=[YOUR-PASSWORD-HERE];"
},
"JWT": {
"ValidAudience": "example-audience",
"ValidIssuer": "example-issuer",
"Secret": "[YOUR-SECRET-HERE]"
}
}
- Change the server, port, and user id as necessary. Replace
[YOUR-USERNAME-HERE]
and[YOUR-PASSWORD-HERE]
with your personal MySQL username and password (set at installation of MySQL). - To properly implement JSON Web Tokens for API authorization, replace
[YOUR-SECRET-HERE]
with your own personalized string.- NOTE: The
Secret
is a special string that will be used to encode our JWTs, to make them unique to our application. Depending on what type of algorithm being used, the Secret string will need to be a certain length. In this case, it needs to be at least 16 characters long.
- NOTE: The
- Navigate to MessageBoardAPI/MessageBoardApi directory using the MacOS Terminal or Windows Powershell (e.g.
cd Desktop/MessageBoardAPI/MessageBoardApi
). - Run the command
dotnet ef database update
to generate the database through Entity Framework Core. - (Optional) To update the database with any changes to the code, run the command
dotnet ef migrations add <MigrationsName>
which will use Entity Framework Core's code-first principle to generate a database update. 4) After, run the previous commanddotnet ef database update
to update the database.
- Navigate to MessageBoardAPI/MessageBoardApi directory using the MacOS Terminal or Windows Powershell (e.g.
cd Desktop/MessageBoardAPI/MessageBoardApi
). - Run the command
dotnet watch run
to have access to the API in Postman or browser.
Explore the API endpoints in Postman or a browser. You will not be able to utilize authentication in a browser.
To explore the MessageBoard API with NSwag, launch the project using dotnet run
with the Terminal or Powershell, and input the following URL into your browser: http://localhost:5000/swagger
In order to be authorized to use the POST, PUT, DELETE functionality of the API, please authenticate yourself through Postman.
Again, we'll be using Postman for this example. Let's setup a POST
request to the accounts/register
endpoint. Select the 'Body' tab, choose the 'raw' radio button, and select 'JSON' from the dropdown selection.
In the Body of the Post request, use the following format:
{
"email": "[email protected]",
"userName": "testUser",
"password": "Password123!"
}
https://localhost:5000/api/accounts/register
{
"status": "success",
"message": "User has been successfully created."
}
Note that the password must contain at least six characters, one non-alphanumeric character, at least one digit lowercase letter, at least one uppercase letter and at least two unique characters. An invalid password will generate the following response from the API:
Now that we've registered an account with our API, we'll need to authenticate our account and generate a JSON Web Token. We'll be using Postman again for this example.
Let's setup another POST
request to the accounts/signin
endpoint. Select the 'Body' tab, choose the 'raw' radio button, and select 'JSON' from the dropdown selection.
In the Body of the Post request, use the following format:
{
"email": "[email protected]",
"password": "Password123!"
}
https://localhost:5000/api/accounts/signin
{
"status": "success",
"message": "[email protected] signed in.",
"token": "xxxx.xxxx.xxxx"
}
Now let's copy that token from the response, and add it as an authorization header to our next request. Copy the token from the body, and click on the Authorization tab in Postman. On the 'Type', make sure that is set to 'Bearer Token', and then paste in the token in the field on the right.
Until the Token expires, you should now have access to all endpoints requiring user authorization!
For some endpoints, the MessageBoard API returns a default of 10 results per page at a time, which is also the maximum number of results possible.
To modify this, use the query parameters pageSize
and pageNumber
to alter the response results displayed. The pageSize
parameter will specify how many results will be displayed, and the pageNumber
parameter will specify which element in the response the limit should start counting.
https://localhost:5000/api/groups/1/messages?pageNumber=1&pageSize=2
To use the defaults, do not include pageNumber
and pageSize
, or, set them equal to zero.
When adding more than one search parameter to an endpoint query, be sure to include an &
between parameters, as shown above in the example query for pagination.
..........................................................................................
Base URL: https://localhost:5000
GET /api/{component}
POST /api/{component}
GET /api/{component}/{id}
PUT /api/{component}/{id}
DELETE /api/{component}/{id}
https://localhost:5000/api/groups/3
{
"groupId": 3,
"name": "Costumes",
"messages": [
{
"messageId": 2,
"text": "What did ya'll get for candy? I got rocks.",
"date": "2023-03-21T06:30:00",
"userId": "abc"
}
]
}
..........................................................................................
Access information on messages posted by MessageBoard users.
GET /api/messages
POST /api/messages
GET /api/messages/{id}
PUT /api/messages/{id}
DELETE /api/messages/{id}
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
groupId | int | none | false | Return matches by group. |
dateFrom | string | none | false | Return any message on or after the specified date. |
dateTo | string | none | false | Return any message on or before the specified date. |
https://localhost:5001/api/messages?groupId=1&dateTo=08/2023
[
{
"messageId": 1,
"text": "This new Spider-Man game looks awesome!",
"date": "2022-12-08T08:15:00",
"groupId": 1,
"userId": "def"
}
]
..........................................................................................
Access information about messages board groups, in which messages are posted.
The GET endpoint for groups/{id}/messages
includes pagination by default. Users may override pagination defaults by including new search parameters.
GET /api/groups
GET /api/groups/{id}
GET /api/groups/{id}/messages
GET /api/groups/{id}/messages/{messageId}
POST /api/groups/{id}/messages
DELETE /api/groups/{id}
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
pageNumber | int | 1 | false | Specifies which element in the response the pageSize limit should start counting from. |
pageSize | int | 10 | false | Returns the specified number of elements per response; default is 10 elements. |
https://localhost:5000/api/groups/1/messages??pageNumber=1&pageSize=2
{
"pageNumber": 1,
"pageSize": 2,
"firstPage": "https://localhost:5001/api/groups/1/messages?pageNumber=1&pageSize=2",
"lastPage": "https://localhost:5001/api/groups/1/messages?pageNumber=2&pageSize=2",
"totalPages": 2,
"totalRecords": 3,
"nextPage": "https://localhost:5001/api/groups/1/messages?pageNumber=2&pageSize=2",
"previousPage": null,
"data": [
{
"messageId": 1,
"text": "This new Spider-Man game looks awesome!",
"date": "2022-12-08T08:15:00",
"groupId": 1,
"userId": "def"
},
{
"messageId": 4,
"text": "Testing a post with tokens.",
"date": "2023-10-25T14:16:54.29078",
"groupId": 1,
"userId": "abc"
}
],
"succeeded": true,
"errors": null,
"message": null
}
Author | GitHub | |
---|---|---|
Joey Palchak | jfpalchak | [email protected] |
Onur Kaymak | onurkaymak | [email protected] |
Richard Barbour | barcode | [email protected] |
If you have any feedback or concerns, please contact one of the contributors.
This project is licensed under the MIT License. Copyright (C) 2023 Joey Palchak, Onur Kaymak and Richard Barbour. All Rights Reserved.
MIT License
Copyright (c) 2023 Joey Palchak, Onur Kaymak and Richard Barbour.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"A school for tech careers... to help people learn the skills they need to get great jobs."
"...the first thing that humanity has built that humanity doesn't understand..."
- Eric Schmidt, Google (Alphabet Inc.)
Return to Top