Home

#coding #web-development #apis

Overview

Vividblog is an api for managing blogs with user authentication built on RESTful principles.

Setting up

Vividblog is built using Flask-RESTfuland uses Marshmallo for data serialisation and validation.

1. First set up your virtual environment using a version of python. More information of how to set up a virtual environment is here

python3 -m venv .venv

2. Then install all required dependancies in the requirements.txt file in the root directory

pip install -r requirements.txt

3. Create a .env file like this

DEV_DATABASE_URL=sqlite:///blog.db
TESTING_DATABASE_URL=sqlite:///blog_test.db
SECRET_KEY=a_random_hash
FLASK_CONFIG=default
SERVER_URL=http://127.0.0.1:5000/api/v1
JWT_SECRET_KEY=a_random_hash
JWT_ACCESS_TOKEN_EXPIRES=30

You can generate random hashes here

4. Run the app

./auto/boot.bat # Windows
./auto/boot.sh #Linux/MacOS

Auth

Authentication is by JWT

Login Authentication endpoint: /api/v1/auth/login (POST) Signup Authentication endpoint: /api/v1/user (POST)

Request:

{
	"username" : "Ezekiel",
	"password" : "mypassword"
}

Response:

{
	"access_token": "An access token to use in your header"
}

By default a JWT only lasts for 30 minutes. but you can change it in your .env file

JWT_ACCESS_TOKEN_EXPIRES=<random number>

Responses

The following are the types of responses to be expected from this api

Note

Wherever null was recorded as a response and there was a 200 status code, this automatically returns this 200 message

404

Returned when a requested resource is not found

{
	"message": "Not found"
}

200

Returned when an operation is succesful but no response is returned

{
	"Message": "Operation Succesful"
}

401

Returned when no valid credentials are provided

{
	"msg": "Token has expired"
}

Endpoints

The following are the endpoints that exists on the api

An endpoint communicates two things

1. The Request Payload - Data sent from the client to the server
2. The Response Payload - Data sent from the server to the client

User Endpoints

Endpoints	Available Methods	Description	Parameters
/api/v1/users	POST, GET	Deals with a list of users
/api/v1/users/<userid>	GET, PUT, DELETE	Deals with an individual user
/api/v1/users/<userid>/blogs	GET	Deals with the blog of a particular user lar

/api/v1/users

POST

Description: Create a new User

Request:

{
"username" : "John Doe",
"emailaddress" : "[email protected]",
"password": "drowssap",
"title": "Technical Writer"
}

Response

null

GET

Description: Get all users

Query Parameters:

• currentPage: The current page of the response
• itemsPerPage: The number of items in a particular page
• username: Search query by username

Request:

null

Response

{
	"users": [
		{
			"id": "354ca710-9d1a-43cc-a03b-2a7a66af6c78",
			"username": "Charles",
			"email_address": "[email protected]",
			"title": "Beginner",
			"followers": 0,
			"avatar_url": "https://www.robohash.org/[email protected]",
			"date_joined": "2022-09-18T00:18:48",
			"user_url": "http://127.0.0.1:5000/api/v1/users/354ca710-9d1a-43cc-a03b-2a7a66af6c78"
		},
		{
			"id": "edb0dd2c-4515-4e21-8692-342b79af77ff",
			"username": "Amber",
			"email_address": "[email protected]",
			"title": "Beginner",
			"followers": 0,
			"avatar_url": "https://www.robohash.org/[email protected]",
			"date_joined": "2022-05-28T05:27:00",
			"user_url": "http://127.0.0.1:5000/api/v1/users/edb0dd2c-4515-4e21-8692-342b79af77ff"
		}
	],
	"total_pages": 100,
	"page": "2",
	"page_number": 2,
	"next_page": "http://127.0.0.1:5000/api/v1/users?currentPage=3&itemsPerPage=2",
	"previous_page": "http://127.0.0.1:5000/api/v1/users?currentPage=1&itemsPerPage=2"
}

`/api/v1/users/

`

GET

Description: Get a Single user

Request:

null

Response

{
	"id": "4c7d516a-8509-4fa6-a9f9-5db1796833b2",
	"username": "Michael",
	"email_address": "[email protected]",
	"title": "Beginner",
	"followers": 0,
	"avatar_url": "https://www.robohash.org/[email protected]",
	"date_joined": "2021-05-16T02:43:46"
}

PUT (auth_required)

Description: Update a user's Information

Request:

{
	"username" : "Ezekiel",
	"email_address" : "[email protected]",
	"title" : "Technical Writer",
	"password" : "damilola"
}

Response

null

DELETE (auth_required)

Description: Delete a particular user

Request:

null

Response

null

/api/v1/users/<userid>/blogs

GET

Description: Get the blogs of a particular user

Request:

null

Response

{
	"blogs": [
		{
			{
    "id": "dc34a0bb-c264-48e2-a232-b37af6d30bca",
    "title": "Age break ball member up.",
    "introduction": "Occur this likely weight drug energy fear authority quickly.",
    "ingredients_involved": [
        "carrot\n",
        "tomato\n",
        "flour\n"
    ],
    "steps_involved": [
        "Mrs management check meeting. Physical avoid us air gun.",
        "Program course else summer those agreement. Seven president measure experience half place. Reduce use he and central attorney realize. President point institution.",
        "Recently character public class loss green. Rule consumer suffer foreign participant.",
        "List debate individual theory. Factor prove executive song.",
        "Information believe son white company say ever. Across during majority tax soon.",
        "Score her probably forget right. Politics citizen option ball.",
        "Sound third information north people account. My set behavior per.",
        "Small me coach despite administration onto realize. Great position himself.",
        "Future wrong sound score. Positive investment camera hotel. All continue ability science."
    ],
    "conclusion": "Big while easy feel room off hour always necessary end shoulder.",
    "created": "2024-01-18T10:51:42",
    "updated": null,
    "likes": 0,
    "comments_number": 5,
    "author_id": "354ca710-9d1a-43cc-a03b-2a7a66af6c78",
    "comments_url": "http://127.0.0.1:5000/api/v1/blogs/dc34a0bb-c264-48e2-a232-b37af6d30bca/comments"
}
		}
	]
}

Blog Endpoints

Endpoint	Available Methods	Description
/api/v1/blogs	GET, POST	Dealing with a list of blo
/api/v1/blogs/<blogid>	GET, PUT, DELETE	Dealing with a particular b
/api/v1/blogs/<blogid>/comments	GET, POST	Dealing with a blog's coments
/api/v1/blogs/<blogid>/comments/<commentid>	GET, PUT, DELE	Dealing with a comment of a particulatr blog.

/blogs

POST (auth required)

Description: Add a blog

Request:

{
    "title": "How to Make Marshmallows",
    "introduction": "Marshmallows are sweet, fluffy treats that can be made at home with a few basic ingredients.",
    "ingredients_involved": [
        "2 tablespoons gelatin",
        "1/2 cup cold water",
        "2 cups granulated sugar",
        "1/2 cup corn syrup",
        "1/2 cup hot water",
        "1 teaspoon vanilla extract",
        "Pinch of salt",
        "Powdered sugar for dusting"
    ],
    "steps_involved": [
        "Sprinkle gelatin over cold water and let it bloom.",
        "In a saucepan, mix sugar, corn syrup, and hot water, then bring to a boil.",
        "Once boiling, pour into the gelatin mixture and mix with an electric mixer on high speed until fluffy.",
        "Add vanilla extract and salt, then continue mixing until soft peaks form.",
        "Pour the mixture into a greased and powdered sugar-dusted dish.",
        "Let it set for at least 4 hours, then cut into cubes and dust with powdered sugar."
    ],
    "conclusion": "Enjoy your homemade marshmallows! Store them in an airtight container to keep them fresh.", 
	"author_id" : "A random uuid"
}

Response:

null

GET

Description: Get all blogs Query Parameters:

• currentPage: The current page of the response
• itemsPerPage: The number of items in a particular page
• username: Search query by username

Request:

null

Response:

{
	"blogs": [
		{
			"id": "2d02075d-ce2d-43a8-ad72-527db475525c",
			"title": "Choice provide able identify national.",
			"introduction": "Room prove issue far time site machine court agree head.",
			"ingredients_involved": [
				"potato\n",
				"garlic\n",
				"sugar\n",
				"baking powder\n",
				"eggs\n",
				"vanilla extract\n",
				"beef\n"
			],
			"steps_involved": [
				"Upon whom system station move remember. Woman yeah size change. Tend on good meeting.",
				"Thank life coach actually pay ask yet. Us more occur ability.",
				"Little yourself its organization hundred relate act individual. Experience place determine letter social effort me. Strategy student visit indicate issue ahead assume real.",
				"Wish lose away speak office. Cup child PM group. Some than cell in.",
				"Investment nature interest outside PM order discover. Product television early expert opportunity view some. Strong necessary citizen worry final memory."
			],
			"conclusion": "Art hope strategy so beat offer think crime however reason especially.",
			"created": "2024-02-17T12:45:28",
			"updated": null,
			"likes": 0,
			"comments_number": 6,
			"author_id": "fc3ad8e9-b77b-45f5-ac25-e6aaec395e57",
			"blog_url": "http://127.0.0.1:5000/api/v1/blogs/2d02075d-ce2d-43a8-ad72-527db475525c",
			"author_url": "http://127.0.0.1:5000/api/v1/users/fc3ad8e9-b77b-45f5-ac25-e6aaec395e57"
		}
	],
	"total_pages": 1001,
	"page": 1,
	"page_number": 1,
	"next_page": "http://127.0.0.1:5000/api/v1/blogs?currentPage=2",
	"previous_page": null
}

/blogs/<blogid>

PUT (auth_required)

Description: update a particular blog Request

{
    "title": "How to Make Marshmallows",
    "introduction": "Marshmallows are sweet, fluffy treats that can be made at home with a few basic ingredients.",
    "ingredients_involved": [
        "2 tablespoons gelatin",
        "1/2 cup cold water",
        "2 cups granulated sugar",
        "1/2 cup corn syrup",
        "1/2 cup hot water",
        "1 teaspoon vanilla extract",
        "Pinch of salt",
        "Powdered sugar for dusting"
    ],
    "steps_involved": [
        "Sprinkle gelatin over cold water and let it bloom.",
        "In a saucepan, mix sugar, corn syrup, and hot water, then bring to a boil.",
        "Once boiling, pour into the gelatin mixture and mix with an electric mixer on high speed until fluffy.",
        "Add vanilla extract and salt, then continue mixing until soft peaks form.",
        "Pour the mixture into a greased and powdered sugar-dusted dish.",
        "Let it set for at least 4 hours, then cut into cubes and dust with powdered sugar."
    ],
    "conclusion": "Enjoy your homemade marshmallows! Store them in an airtight container to keep them fresh.",
    "author_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response

null

GET

Description: Get a particular blog Request

null

Response

{
	"id": "712c07e3-3e14-46b2-aa53-2f3e6ad81a49",
	"title": "Throughout war east couple ago memory record word.",
	"introduction": "Staff foreign speak almost class expert president across allow work pass hospital herself city tell fall.",
	"ingredients_involved": [
		"potato\n",
		"olive oil\n",
		"potato\n",
		"sugar\n",
		"beef\n",
		"rice\n"
	],
	"steps_involved": [
		"Beautiful organization unit finally Mrs activity. Education trouble their rule consumer.",
		"Friend important say form significant structure deal animal. Serious for room radio once late.",
		"Certain suffer collection participant believe where she. Eye word on into become exist part.",
		"Dinner article south it politics hold. Than consumer mind degree baby once close TV.",
		"Nor into when music unit remember. Later race air possible beautiful chair.",
		"Make program listen join indicate rich. Them everyone local account response security happen. Exactly speak girl idea wrong.",
		"Toward remember good both. Call box gun or fire none nice. Police situation country describe pattern defense must position. Least for method safe high capital believe.",
		"Would security American opportunity. Series onto read focus. Two any person budget agreement final popular focus.",
		"Parent attention mission word edge even. Poor like thing right police professor different. Baby painting politics him stuff physical."
	],
	"conclusion": "Result art large course cup heart provide total consider include actually environment trade hair.",
	"created": "2024-03-13T16:10:26",
	"updated": null,
	"likes": 0,
	"comments_number": 1,
	"author_id": "50f8bfb9-2e8f-479e-9da9-ecac6f343180",
		"comments_url": "http://127.0.0.1:5000/api/v1/blogs/712c07e3-3e14-46b2-aa53-2f3e6ad81a49/comments"
}

DELETE (auth_required)

Description: Delete a particular blog

Request

null

Response

null

/blog/<blogid>/comments

POST (auth_required)

Description: Create a comment for a blog

Request

Response

null

GET

Description: Get comments for a blog

Request

null

Response

{
	"No of comments": 2,
	"comments": [
		{
			"id": "1d784b02-fd30-426a-98e9-095a94cae418",
			"message": "Structure community protect performance impact parent a bed seat group everyone sister.",
			"author_id": "c79e9131-4db2-4288-89ca-a61af26b5b56",
			"blog_id": "519e9264-7e18-4a52-8f08-eec9ccbb8eb8",
			"date_written": "2024-02-01 13:23:48"
		},
		{
			"id": "bd301086-b0ba-4ebd-9b58-7377229035cf",
			"message": "Whether final already together single happy player national professional every our fire strong write reveal.",
			"author_id": "9ab65189-755d-4cc7-8863-b271b24a3bd4",
			"blog_id": "519e9264-7e18-4a52-8f08-eec9ccbb8eb8",
			"date_written": "2024-03-02 22:01:45"
		}
	]
}

/blog/<blogid>/comments/<commentid>

GET

Description: Get a particular comment from a particular blog

Request:

null

Response:

{
	"id": "1d784b02-fd30-426a-98e9-095a94cae418",
	"message": "Structure community protect performance impact parent a bed seat group everyone sister.",
	"author_id": "c79e9131-4db2-4288-89ca-a61af26b5b56",
	"blog_id": "519e9264-7e18-4a52-8f08-eec9ccbb8eb8",
	"date_written": "2024-02-01 13:23:48"
}

DELETE (auth_required)

Description: Delete a particular comment for a particular blog

Request:

null

Response:

null