https://github.com/ipenywis/clean-rest-apis
Best Practices to write clean RESTFUL APIs using Node.js and Express
https://github.com/ipenywis/clean-rest-apis
Last synced: 4 months ago
JSON representation
Best Practices to write clean RESTFUL APIs using Node.js and Express
- Host: GitHub
- URL: https://github.com/ipenywis/clean-rest-apis
- Owner: ipenywis
- Created: 2023-02-27T14:38:07.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-02-27T14:38:59.000Z (about 2 years ago)
- Last Synced: 2024-08-13T07:17:07.828Z (8 months ago)
- Language: TypeScript
- Size: 21.5 KB
- Stars: 112
- Watchers: 2
- Forks: 32
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- jimsghstars - ipenywis/clean-rest-apis - Best Practices to write clean RESTFUL APIs using Node.js and Express (TypeScript)
README
# REST API Example
This example shows how to implement a **REST API with TypeScript** using [Express](https://expressjs.com/) and [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client). The example uses an SQLite database file with some initial dummy data which you can find at [`./prisma/dev.db`](./prisma/dev.db).
## Getting started
### 1. Download example and install dependencies
Download this example:
```
npx try-prisma --template typescript/rest-express
```
Install npm dependencies:
```
cd rest-express
npm install
```
Alternative: Clone the entire repo
Clone this repository:
```
git clone [email protected]:prisma/prisma-examples.git --depth=1
```
Install npm dependencies:
```
cd prisma-examples/typescript/rest-express
npm install
```
### 2. Create and seed the database
Run the following command to create your SQLite database file. This also creates the `User` and `Post` tables that are defined in [`prisma/schema.prisma`](./prisma/schema.prisma):
```
npx prisma migrate dev --name init
```
When `npx prisma migrate dev` is executed against a newly created database, seeding is also triggered. The seed file in [`prisma/seed.ts`](./prisma/seed.ts) will be executed and your database will be populated with the sample data.
### 3. Start the REST API server
```
npm run dev
```
The server is now running on `http://localhost:3000`. You can now run the API requests, e.g. [`http://localhost:3000/feed`](http://localhost:3000/feed).
## Using the REST API
You can access the REST API of the server using the following endpoints:
### `GET`
- `/post/:id`: Fetch a single post by its `id`
- `/feed?searchString={searchString}&take={take}&skip={skip}&orderBy={orderBy}`: Fetch all _published_ posts
- Query Parameters
- `searchString` (optional): This filters posts by `title` or `content`
- `take` (optional): This specifies how many objects should be returned in the list
- `skip` (optional): This specifies how many of the returned objects in the list should be skipped
- `orderBy` (optional): The sort order for posts in either ascending or descending order. The value can either `asc` or `desc`
- `/user/:id/drafts`: Fetch user's drafts by their `id`
- `/users`: Fetch all users
### `POST`
- `/post`: Create a new post
- Body:
- `title: String` (required): The title of the post
- `content: String` (optional): The content of the post
- `authorEmail: String` (required): The email of the user that creates the post
- `/signup`: Create a new user
- Body:
- `email: String` (required): The email address of the user
- `name: String` (optional): The name of the user
- `postData: PostCreateInput[]` (optional): The posts of the user
### `PUT`
- `/publish/:id`: Toggle the publish value of a post by its `id`
- `/post/:id/views`: Increases the `viewCount` of a `Post` by one `id`
### `DELETE`
- `/post/:id`: Delete a post by its `id`
## Evolving the app
Evolving the application typically requires two steps:
1. Migrate your database using Prisma Migrate
1. Update your application code
For the following example scenario, assume you want to add a "profile" feature to the app where users can create a profile and write a short bio about themselves.
### 1. Migrate your database using Prisma Migrate
The first step is to add a new table, e.g. called `Profile`, to the database. You can do this by adding a new model to your [Prisma schema file](./prisma/schema.prisma) file and then running a migration afterwards:
```diff
// ./prisma/schema.prisma
model User {
id Int @default(autoincrement()) @id
name String?
email String @unique
posts Post[]
+ profile Profile?
}
model Post {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
title String
content String?
published Boolean @default(false)
viewCount Int @default(0)
author User? @relation(fields: [authorId], references: [id])
authorId Int?
}
+model Profile {
+ id Int @default(autoincrement()) @id
+ bio String?
+ user User @relation(fields: [userId], references: [id])
+ userId Int @unique
+}
```
Once you've updated your data model, you can execute the changes against your database with the following command:
```
npx prisma migrate dev --name add-profile
```
This adds another migration to the `prisma/migrations` directory and creates the new `Profile` table in the database.
### 2. Update your application code
You can now use your `PrismaClient` instance to perform operations against the new `Profile` table. Those operations can be used to implement API endpoints in the REST API.
#### 2.1 Add the API endpoint to your app
Update your `index.ts` file by adding a new endpoint to your API:
```ts
app.post('/user/:id/profile', async (req, res) => {
const { id } = req.params
const { bio } = req.body
const profile = await prisma.profile.create({
data: {
bio,
user: {
connect: {
id: Number(id)
}
}
}
})
res.json(profile)
})
```
#### 2.2 Testing out your new endpoint
Restart your application server and test out your new endpoint.
##### `POST`
- `/user/:id/profile`: Create a new profile based on the user id
- Body:
- `bio: String` : The bio of the user
Expand to view more sample Prisma Client queries on Profile
Here are some more sample Prisma Client queries on the new Profile model:
##### Create a new profile for an existing user
```ts
const profile = await prisma.profile.create({
data: {
bio: 'Hello World',
user: {
connect: { email: '[email protected]' },
},
},
})
```
##### Create a new user with a new profile
```ts
const user = await prisma.user.create({
data: {
email: '[email protected]',
name: 'John',
profile: {
create: {
bio: 'Hello World',
},
},
},
})
```
##### Update the profile of an existing user
```ts
const userWithUpdatedProfile = await prisma.user.update({
where: { email: '[email protected]' },
data: {
profile: {
update: {
bio: 'Hello Friends',
},
},
},
})
```
## Switch to another database (e.g. PostgreSQL, MySQL, SQL Server, MongoDB)
If you want to try this example with another database than SQLite, you can adjust the the database connection in [`prisma/schema.prisma`](./prisma/schema.prisma) by reconfiguring the `datasource` block.
Learn more about the different connection configurations in the [docs](https://www.prisma.io/docs/reference/database-reference/connection-urls).
Expand for an overview of example configurations with different databases
### PostgreSQL
For PostgreSQL, the connection URL has the following structure:
```prisma
datasource db {
provider = "postgresql"
url = "postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA"
}
```
Here is an example connection string with a local PostgreSQL database:
```prisma
datasource db {
provider = "postgresql"
url = "postgresql://janedoe:mypassword@localhost:5432/notesapi?schema=public"
}
```
### MySQL
For MySQL, the connection URL has the following structure:
```prisma
datasource db {
provider = "mysql"
url = "mysql://USER:PASSWORD@HOST:PORT/DATABASE"
}
```
Here is an example connection string with a local MySQL database:
```prisma
datasource db {
provider = "mysql"
url = "mysql://janedoe:mypassword@localhost:3306/notesapi"
}
```
### Microsoft SQL Server
Here is an example connection string with a local Microsoft SQL Server database:
```prisma
datasource db {
provider = "sqlserver"
url = "sqlserver://localhost:1433;initial catalog=sample;user=sa;password=mypassword;"
}
```
### MongoDB
Here is an example connection string with a local MongoDB database:
```prisma
datasource db {
provider = "mongodb"
url = "mongodb://USERNAME:PASSWORD@HOST/DATABASE?authSource=admin&retryWrites=true&w=majority"
}
```
## Next steps
- Check out the [Prisma docs](https://www.prisma.io/docs)
- Share your feedback in the [`#product-wishlist`](https://prisma.slack.com/messages/CKQTGR6T0/) channel on the [Prisma Slack](https://slack.prisma.io/)
- Create issues and ask questions on [GitHub](https://github.com/prisma/prisma/)
- Watch our biweekly "What's new in Prisma" livestreams on [Youtube](https://www.youtube.com/channel/UCptAHlN1gdwD89tFM3ENb6w)