1. 기본 원칙

• 데이터 형식: 모든 데이터는 JSON 형식으로 주고 받습니다.
• Base URL: API의 기본 주소가 정해지면 알려주세요 (예: https://api.calolink.com/...)
• 에러 처리: "3. 에러처리"에 정의된 HTTP 상태코드를 사용해 에러 상황을 알려주세요
  (추가나 변경이 필요하면 같이 얘기해도 좋을거 같아요)

2. API 명세

API 1: 상품 목록 검색

• 사용자가 입력한 검색어, 필터, 정렬 조건에 맞는 상품 목록을 "페이지 단위"로 반환하는 가장 핵심적인 API 입니다.
• HTTP Method: GET

요청 (Request)

• 설명: iOS 앱은 아래와 같은 조건들을 "URL 쿼리 파라미터"에 담아 서버에 요청을 보냅니다.
• 예시: GET /products/search?query=닭가슴살&sort=priceAscending&maxCalories=200&page=1 (base URL 생략)

URL 쿼리 파라미터(Query Parameter)를 통해 아래와 같은 검색 조건을 전달합니다.

Key	타입	필수 여부	설명	예시
query	String	선택	검색어	닭가슴살
sort	String	필수	정렬 기준 defaultOrder 등	priceAscending
page	Int	필수	요청할 페이지 번호(1부터 시작)	1
minCalories	Double	선택	최소 칼로리 (kcal)	100
maxCalories	Double	선택	최대 칼로리 (kcal)	300
minSodium	Double	선택	최소 나트륨 (mg)	100
maxSodium	Double	선택	최대 나트륨 (mg)	500
minCarbs	Double	선택	최소 탄수화물 (g)	10
maxCarbs	Double	선택	최대 탄수화물 (g)	30
minSugars	Double	선택	최소 당류 (g)	0
maxSugars	Double	선택	최대 당류 (g)	10
minFat	Double	선택	최소 지방 (g)	5
maxFat	Double	선택	최대 지방 (g)	15
minTransFat	Double	선택	최소 트랜스지방 (g)	0
maxTransFat	Double	선택	최대 트랜스지방 (g)	0
minSaturatedFat	Double	선택	최소 포화지방 (g)	0
maxSaturatedFat	Double	선택	최대 포화지방 (g)	5
minCholesterol	Double	선택	최소 콜레스테롤 (mg)	0
maxCholesterol	Double	선택	최대 콜레스테롤 (mg)	50
minProtein	Double	선택	최소 단백질 (g)	25
maxProtein	Double	선택	최대 단백질 (g)	50

응답 (Response)

• 요청이 성공하면 (200 OK), 서버는 아래와 같은 구조의 JSON을 응답 Body에 담아 보내줍니다.
• products배열의 순서는 요청받은 sort기준에 따라 반드시 정렬된 상태여야 합니다.

{
    "products": [
        {
            "id": "P001",
            "name": "맛있는 닭가슴살 100g",
            "imageURL": "https://example.com/image.jpg",
            "price": 2500,
            "keyNutrients": [
                { "name": "단백질", "value": "25g" },
                { "name": "칼로리", "value": "130kcal" }
            ]
        }
    ],
    "totalPages": 10,
    "currentPage": 1
}

API 2: 상품 상세 정보 조회

• 사용자가 목록에서 특정 상품을 선택했을 때 해당 상품의 모든 상세 정보를 반환하는 API 입니다.
• HTTP Method: GET

요청 (Request)

• URL 경로에 상품의 고유 ID를 담아 요청합니다.
• 예시: GET /products/P001 (base URL 생략)

응답 (Response)

• 요청 성공 시(200 OK), 아래 구조의 JSON을 Body에 담아 보내주세요.
• percentage나 amount처럼 값이 없는 필드는 null로 반환합니다.

{
    "id": "P001",
    "name": "맛있는 닭가슴살 100g",
    "imageURL": "https://example.com/image.jpg",
    "nutritionInfo": {
        "totalSize": 100,
        "calories": 130,
        "sodium": { "amount": 300, "unit": "mg", "percentage": 15 },
        "carbs": { "amount": 2, "unit": "g", "percentage": 1 },
        "sugars": { "amount": 1, "unit": "g", "percentage": null },
        "protein": { "amount": 25, "unit": "g", "percentage": 50 }
    },
    "shopLinks": [
        {
            "mallName": "쿠팡",
            "price": 2500,
            "linkURL": "https://coupang.com/products/P001"
        }
    ]
}

3. 에러 처리 (상태 코드)

아래와 같은 상황에서는 약속된 HTTP 상태 코드를 반환해주세요.

상태 코드	의미	설명
200 OK	성공	요청이 성공적으로 처리되었습니다.
400 Bad Request	잘못된 요청	필수 파라미터가 누락되었거나, 타입이 잘못되었습니다.
404 Not Found	리소스 없음	존재하지 않는 상품 ID로 상세 정보를 요청했습니다.
500 Internal Server Error	서버 내부 오류	예측하지 못한 서버 내부 문제가 발생했습니다.