Flask로 웹개발: #14 API 문서 작성

이제 우리의 웹개발이 끝난거 같은데 뭐가 더 남았을까요? ㅎㅎ 아쉽게도(!?) 웹개발에서 한가지 중요한 부분이 더 남아있습니다. 어쩌면, 우리가 지금까지 했던 개발보다 지금할 개발 작업이 실무에서는 더 많이 일어날지도 모르겠습니다. 바로 API 개발입니다. API란 Application Programming Interface의 약자로 프로그램에 의해 호출되어 어떤 기능을 수행하는 기능을 의미합니다. 눈에 보이지는 않지만 컴퓨터로 어떤 작업을 수행할 때 유용한 기능입니다.
이 포스팅에서는 앞서 만들었던 제품 정보를 제어하기 위한 API를 정의합니다. API를 통해 제품을 등록하거나 삭제하는 기능을 구현한다는 이야기입니다. 각 엔드포인트는 CRUD (Create, Read, Update, Delete) 기능을 수행하며, **JSON 형식의 요청 및 응답을 사용합니다. 이번 포스팅은 API 문서와 유사한 형태로 진행됩니다. 어쩌면, 조금 딱딱한 느낌이 들 수도 있겠습니다.
API 엔드포인트 요약
- POST /api/products: 새로운 제품을 생성합니다.
- GET /api/products: 모든 제품 목록을 가져옵니다.
- GET /api/products/int:product_id: 특정 제품의 상세 정보를 가져옵니다.
- PUT /api/products/int:product_id: 특정 제품의 정보를 업데이트합니다.
- DELETE /api/products/int:product_id: 특정 제품을 삭제합니다.
1. Create a New Product
Endpoint
POST /api/products
Description
새로운 제품을 생성합니다
Request Body
{
"name": "Product Name",
"price": 99.99,
"description": "Product Description",
}
Response
- 201 Created: 성공적으로 제품이 생성된 경우
{
"id": 1,
"name": "Product Name",
"price": 99.99,
"description": "Product Description",
}
- 400 Bad Request: 요청 데이터가 유효하지 않은 경우
2. Retrieve All Products
Endpoint
GET /api/products
Description
모든 제품 목록을 가져옵니다.
Response
- 200 OK: 성공적으로 제품 목록을 반환한 경우
[
{
"id": 1,
"name": "Product 1",
"price": 99.99,
"description": "Description 1",
},
{
"id": 2,
"name": "Product 2",
"price": 49.99,
"description": "Description 2",
}
]
3. Retrieve a Single Product
Endpoint
GET /api/products/<int:product_id>
Description
특정 제품의 상세 정보를 가져옵니다.
Response
- 200 OK: 성공적으로 제품 정보를 반환한 경우
{
"id": 1,
"name": "Product Name",
"price": 99.99,
"description": "Product Description",
}
- 404 Not Found: 요청한 제품을 찾을 수 없는 경우
4. Update a Product
Endpoint
PUT /api/products/<int:product_id>
Description
특정 제품의 정보를 업데이트합니다.
Request Body
{
"name": "Updated Product Name",
"price": 89.99,
"description": "Updated Product Description",
}
Response
- 200 OK: 성공적으로 제품 정보가 업데이트된 경우
{
"id": 1,
"name": "Updated Product Name",
"price": 89.99,
"description": "Updated Product Description",
}
- 400 Bad Request: 요청 데이터가 유효하지 않은 경우
- 404 Not Found: 요청한 제품을 찾을 수 없는 경우
5. Delete a Product
Endpoint
DELETE /api/products/<int:product_id>
Description
특정 제품을 삭제합니다.
Response
- 204 No Content: 성공적으로 제품이 삭제된 경우
- 404 Not Found: 요청한 제품을 찾을 수 없는 경우
결론
이번 포스팅에서는 Flask를 사용하여 미니 쇼핑몰 프로젝트에서 제품 정보를 제어하기 위한 API를 정의하고 구현하는 방법을 다루었습니다. API는 CRUD (Create, Read, Update, Delete) 기능을 통해 제품 정보를 효과적으로 관리할 수 있도록 설계되었습니다. 각 엔드포인트는 JSON 형식의 요청 및 응답을 처리하며, 제품 정보를 생성, 조회, 업데이트, 삭제하는 기능을 포함하고 있습니다.
요약
- Create: POST /api/products 엔드포인트를 통해 새로운 제품을 생성.
- Read: GET /api/products와 GET /api/products/int:product_id 엔드포인트를 통해 모든 제품 목록과 특정 제품 정보를 조회.
- Update: PUT /api/products/int:product_id 엔드포인트를 통해 특정 제품 정보를 업데이트.
- Delete: DELETE /api/products/int:product_id 엔드포인트를 통해 특정 제품을 삭제.
이 API를 통해 개발자들은 미니 쇼핑몰 프로젝트에서 제품 정보를 유연하고 효율적으로 관리할 수 있습니다. Flask와 SQLAlchemy를 사용하여 데이터베이스와의 상호작용을 쉽게 처리할 수 있으며, 더미 데이터를 이용한 테스트를 통해 API의 기능을 검증할 수 있습니다.
더 나아가, 이번 포스팅의 내용을 기반으로 보안 강화, 추가 기능 구현, 그리고 배포 환경 확장을 통해 더욱 완성도 높은 애플리케이션을 개발해 나갈 수 있을 것입니다.
API 기능에 대한 문서화를 해보았습니다. 다음 포스팅에서는 오늘 작성한 API 문서를 바탕으로 기능을 개발해 볼 것입니다. Flask 강의를 잘 따라오셨다면, 뭔가 주기를 가지고 있는 것 같지 않으신가요? 네, 맞습니다. 필요한 기능(요구)가 있고 이 기능에 대해 문서화를 합니다. 문서화 한 다음 기능 개발을 진행하는 루틴을 가지고 있습니다. 실제 비즈니스에서는 중간에 더 많은 작업들이 추가될 수도 있지만 기본적으로 개발업무라는 것이 이러한 루틴을 따라가는 경향이 있습니다. 또한, 이런 루틴을 따르는 것이 비효율을 줄일 수 있는 방법이기도 합니다. 여러분도 이러한 작업 루틴을 잘 익혀드시면 좋겠습니다.
도움이 되셨다면 공감 부탁드리겠습니다. 여러분의 공감이 정말 큰 힘이 됩니다.
감사합니다!