LinkFree API Design

[gptkrsh]

API Design

API

This is a draft on how we can design the API for EddieHubCommunity/LinkFree.

LinkFree consists of 4 main data models:

1. User Profile
2. User Link
3. User Events
4. User Testimonials

Links and User Profiles are the main data models. Events and Testimonials are optional.

Links and User Profiles also have a clicks/views counter.

User Profile

GET /api/users - Returns Array of All Users (with brief stats)
GET /api/users/:username - Returns User Profile (Also Updates Clicks/Views Counter, includes stats)
POST /api/users - Creates Or Updates A New User Profile (Requires GitHub Access Token)
DELETE /api/users - Deletes A User Profile (Requires GitHub Access Token)

In the POST and DELETE requests, the github access token will be used to get the user's GitHub username (github username = linkfree username).

In the POST request, you must also give it a user profile object. When updating a user profile, you must first make a GET request to get the user profile, then update the user profile object, then send it in the POST request.

User Link

Note: User Links are not stored in the database. They are stored in the user profile. The API will handle updating the counter/redirecting for the user link.
Note: The stats for the link will not be limited to the user profile. It will be a separate collection with the url as the key.

GET /api/links - Returns Array of All Links (with brief stats)
GET /api/links/:url - Redirects To The URL (Also Updates Clicks/Views Counter)
GET /api/links/:url/stats - Returns Stats For The URL

User Events

GET /api/events - Returns Array of All Events (with brief stats)
GET /api/events/:id - Returns Event (Also Updates Clicks/Views Counter, includes stats)
POST /api/events - Creates A New Event (Requires GitHub Access Token)
PUT /api/events - Lists the maker of this request as an participant (Requires GitHub Access Token)
DELETE /api/events - Deletes An Event (Requires GitHub Access Token) (You can only delete events that only have you as a participant)

User Testimonials

Note: This is a sub-collection of the User Profile. The API will handle updating the counter/redirecting for the user link

GET /api/users/:username/testimonials - Returns Array of All Testimonials (with brief stats) (Requires GitHub Access Token)
GET /api/users/:username/testimonials/:id - Returns Testimonial (Also Updates Clicks/Views Counter, includes stats) (Requires GitHub Access Token)
POST /api/users/:username/testimonials - Creates A New Testimonial (Requires GitHub Access Token)
PATCH /api/users/:username/testimonials/:id - If you are the author of the testimonial, you can update it.
PUT /api/users/:username/testimonials/:id - Enable or Disable a testimonial, must be profile owner (Requires GitHub Access Token)
DELETE /api/users/:username/testimonials/:id - Deletes A Testimonial (Requires GitHub Access Token)

Rate Limiting

The API will have a rate limit of 6 requests per every minute per IP address. This is to prevent abuse.

If you have a gh token, you can make 12 requests per minute.

Authentication

The API will use GitHub OAuth for authentication. We will use the GitHub API to get the user's GitHub username (github username = linkfree username).

Database

Can we use Prisma for the database? I think it would be a good idea. Especially since Prisma can insert and update data at the same time using the upsert method. This will make it much faster on the API side.

Also Mongoose does not work well with Edge functions. (Easiest way people self host LinkFree is by using Edge functions.)

Other

This is a draft. I am open to suggestions.

[eddiejaoude]

Thanks Krish 👍 we probably could add Swagger to the NextJS project https://www.npmjs.com/package/next-swagger-doc