2022. 5. 13. 15:09γπ Web
μ¬μ΄λ νλ‘μ νΈλ₯Ό μ§ννλ©΄μ μ¬λ°λ₯Έ REST API λμμΈμ μμ§ν΄μΌκ² λ€κ³ λκ»΄ μλ ν¬μ€νΈλ₯Ό λ²μνκ² λμ΅λλ€ (μ½κ°μ μμμ΄ μμ μ μμ΅λλ€)
μ€νλ μ€μμ΄ μμ κ²½μ° λκΈλ‘ μλ €μ£Όμλ©΄ λΉ λ₯΄κ² μμ νλλ‘ νκ² μ΅λλ€.
15 fundamental tips on REST API design
REST APIs are one of the most common types of web services available, but they’re also hard to design. They allow various clients including…
medium.com
REST API λ κ°μ₯ μΌλ°μ μΈ μΉ μλΉμ€ λμμΈμΌλ‘ μλ €μ Έ μμ§λ§ λμμ μ€κ³νκΈ° μ΄λ €μ΄ νΉμ§λ μλ€.
λΈλΌμ°μ , λ°μ€ν¬ν± μ±, λͺ¨λ°μΌ μ ν리μΌμ΄μ λ° κΈ°λ³Έμ μΌλ‘ μΈν°λ·μ΄ μ°κ²°λ λͺ¨λ μ₯μΉμ ν΄λΌμ΄μΈνΈμμ REST APIλ‘ μλ²μ ν΅μ ν μ μλ€. λλ¬Έμ μλ¬κ° λ°μνμ§ μλλ‘ REST API λ₯Ό μ λλ‘ μ€κ³νλ κ²μ΄ λ§€μ° μ€μνλ€.
κΈ°λ³Έμ μΈ λ³΄μ, μ¬λ°λ₯Έ HTTP λ©μλ μ¬μ©, μΈμ¦ ꡬν, λ€μν μμ² λ° μλ΅ μ²λ¦¬κΉμ§ λͺ¨λ κ²μ κ³ λ €νλ©΄ API λ₯Ό μ²μλΆν° λ§λλ κ²μ μ¬μ΄ μΌμ΄ μλλ€. μ΄λ² ν¬μ€ν μμ μ’μ API λ₯Ό λ§λ€ μ μλ 15κ°μ§ νλͺ©μ μκ°νκ² λ€., μ΄ λ°©λ²λ€μ μΈμ΄μ ꡬμ λ°μ§ μμΌλ©° λͺ¨λ νλ μμν¬μ κΈ°μ μ μ μ©λ μ μμμ λ°νλ€.
1. endpoint μ λͺ μ¬λ₯Ό μ¬μ©ν κ².
URL κ²½λ‘(μλν¬μΈνΈ)λ₯Ό μ€μ ν λ ν΄λΌμ΄μΈνΈκ° μ‘°ννκ³ μ νλ μν°ν°(λͺ μ¬)λ₯Ό μ¬μ©ν΄μΌ νλ©°, νμ 볡μνμΌλ‘ μ§μ ν΄μΌνλ€. HTTP μμ² λ©μλ μμ²΄κ° λμ¬λ₯Ό λνλ΄κΈ°μ URLμ λμ¬νμ μ¬μ©νμ§ μλλ€.
κ°μ₯ μΌλ°μ μΌλ‘ μ¬μ©λλ HTTP λ©μλλ GET, POST, PATCH, PUT, DELETEλ‘ REST API μ νμλ λ°λμ HTTP λ©μλμμ λλ¬λμΌνλ€.
- GET : 리μμ€λ₯Ό μ‘°ννλ€.
- POST : μλ‘μ΄ λ°μ΄ν°λ₯Ό μλ²μ 보λΈλ€.
- PUT/PATCH : κΈ°μ‘΄ λ°μ΄ν°λ₯Ό μ λ°μ΄νΈ νλ€.
- DELETE : λ°μ΄ν°λ₯Ό μ κ±°νλ€.
μ΄λ¬ν μμΉμ μΌλν΄μ, μ±
λͺ©λ‘μ μ‘°νν λ GET/books
κ°μ κ²½λ‘λ₯Ό λ§λ€μ΄μΌ νλ€. λ§μ°¬κ°μ§λ‘ POST /books
λ μ μ±
μ μΆκ°νκΈ° μν μλν¬μΈνΈλ©°, PUT /books/:id
λ μ§μ λ idλ‘ μ 체 μ±
λ°μ΄ν°λ₯Ό μ
λ°μ΄νΈ, PATCH /books/:id
λ μ±
μ λΆλΆμ μΈ λ³κ²½ μ¬νμ μ
λ°μ΄νΈνλ€. λ§μ§λ§μΌλ‘, DELETE /books/:id
λ μ§μ λ idμ 리μμ€λ₯Ό μμ νλ€.
μμ μμΉμ μΌλνμ¬ books μν°ν°λ₯Ό μ‘°νν΄λ³΄μ.
GOOD : GET /books
BAD : GET /get-books
λ§μ°¬κ°μ§λ‘, λ€λ₯Έ HTTP λ©μλλ μλμ²λΌ μ μν μ μλ€.
POST : POST /books
PUT : PUT /books/:id
PATCH : PATCH /books/:id
DELETE : DELETE /books/:id
μ€μ λ‘ μ λ μ¬μ΄λ νλ‘μ νΈμμ post λ©μλλ₯Ό μ¬μ©νλ λμ GET λ©μλλ₯Ό μ¬μ©νλ©΄μ end-point λ₯Ό /save-store
λΌκ³ μ§λ μ΄μ²κ΅¬λ μλ μ€μλ₯Ό νκΈ°λ νμ΅λλ€..
2. λ°μ΄ν° μ μ‘ ν¬λ§·: JSON (JavaScript Object Notification)
λͺ λ
μ κΉμ§λ§ ν΄λ API μμ²/μλ΅ μμ
μλ λλΆλΆ XMLμ΄ μ¬μ©λλ€. μμ¦μ JSON μ΄ λλΆλΆμ νλ‘κ·Έλ¨μμ API λ°μ΄ν°λ₯Ό μ μ‘νλ νμ€ νμ
μ΄ λλ€.
μλν¬μΈνΈμ μλ΅μΌλ‘ JSON λ°μ΄ν° νμμ λ°ννκ³ , λ§μ°¬κ°μ§λ‘ HTTP μ νμ΄λ‘λλ₯Ό ν΅ν΄ μ 보λ₯Ό μμ²ν λλ JSON νμμ μ¬μ©νλ€.
ν΄λΌμ΄μΈνΈ μΈ‘μμ νμΌμ λ³΄λΌ κ²½μ°μ Form data λ₯Ό μ¬μ©νλ κ²μ΄ μ’μ§λ§, ν μ€νΈμ μ«μλ₯Ό 보λ΄λλ°μ Form Data κ° κ΅³μ΄ νμνμ§ μλ€. λλΆλΆμ νλ μμν¬κ° ν΄λΌμ΄μΈνΈ μΈ‘μμ JSON μ μ§μ μ μ‘ν μ μκΈ° λλ¬Έμ κ΅³μ΄ Form Data νμμ μ¬μ©νμ§ μμλ λλ€.
ν΄λΌμ΄μΈνΈ μΈ‘μμ λ°μ΄ν°λ₯Ό μ μ‘ν λ, JSON λ°μ΄ν°λ₯Ό μ¬λ°λ₯΄κ² ν΄μν μ μλλ‘ μλ΅ ν€λμ Content-Typeμ application/jsonμΌλ‘ μ€μ ν΄μΌ νλ€. ν¬μ€νΈλ§¨μμ ν μ€νΈμ©λλ‘ api ν΅μ μ ν λ reqeust header μμ μ΄λ₯Ό νμΈν μ μλ€.
3. μ μ ν HTTP μν μ½λ
μμ²μ μ±κ³΅/μ€ν¨λ₯Ό λνλ΄κΈ° μν΄ HTTP μν μ½λλ₯Ό νμ μ¬μ©ν΄μΌνλ€. (λΉμ¦λμ€ μ μ± μ λ°λΌ λν μΌν μν μ½λκ° μλ―Ένλ κ²μ λ¬λΌμ§ μ μμμ μΈμ§νμ). μνμ½λμ μλ―Έλ μλμ²λΌ μ¬μ©ν μ μλ€
200 : ν΅μ μ±κ³΅
201 : μμ± μ±κ³΅
400 : ν΄λΌμ΄μΈνΈ μΈ‘μ μλͺ»λ κ²½λ‘ μμ²
401 : μΈμ¦λμ§ μμ μμ²(μ¬μ©μ)
403: μΈκ°λμ§ μμ μμ²(μ¬μ©μ)
404 : NOT FOUND
429: λ무 λ§μ μμ²
5xx : μλ² μλ¬λ₯Ό μλ―Έ
κ²½μ°μ λ°λΌ λ λ€μν μνμ½λκ° μμ§λ§, μν μ½λ λ²μμ μ νμ λλ©΄ ν΄λΌμ΄μΈνΈκ° λ³΄λ€ μμΈ‘ κ°λ₯ν APIλ₯Ό μ¬μ©ν μ μλ€.
4. νμ€νλ λ©μμ§λ₯Ό λ°ννλΌ
μ μ¬ν μλ ν¬μΈνΈμ λν΄ νμ νμ€νλ μλ΅μ μ¬μ©ν΄μΌ νλ€. ν΄λΌμ΄μΈνΈλ λμΌν ꡬ쑰μ μλ΅ νμμ κΈ°λνλ©° κ·Έμ λ°λΌ νλν μ μλ€. μ΄λ μ μ μλ΅ λΏ λ§ μλλΌ, μ€λ₯ λ©μμ§μλ μ μ©λλ€. 컬λ μ ꡬ쑰λ₯Ό μ‘°ννλ κ²½μ°μ response λ³Έλ¬Έμ μλμ²λΌ νΉμ ν ꡬ쑰λ₯Ό μ μ§νλλ‘ μλ΅ ν¬λ§·μ νμ€ν νλ€.
μλμ λ λ°©λ² μ€ μ΄λκ²μ μ¬μ©νλ , νλμ νμ€νλ νμμ μ μ§ ν΄μΌνλ€.
// array of data
[
{
bookId: 1,
name: "The Republic"
},
{
bookId: 2,
name: "Animal Farm"
}
]
// Or like this
{
"data":
// array of data
[
{
"bookId": 1,
"name": "The Republic"
},
{
"bookId": 2,
"name": "Animal Farm"
}
],
"totalDocs": 200,
"nextPageId": 3
}
// POST /books μμ²μ΄ μ±κ³΅μ μΌλ‘ λ°νλμ λ
{
"bookId": 3,
"name": "Brave New World"
}
ν° λ¬Έμ λ μλμ§λ§ "Book Successfully created" κ°μ λ©μμ§λ₯Ό λ°ννλ κ²μ, HTTP μν μ½λμ μ΄λ―Έ ν¨μΆλ μλ―Έλ₯Ό μ€λ³΅ν΄μ νννλ κ²κ³Ό κ°λ€.
{
"code": "book/not_found",
"message": "A book with the ID 6 could not be found"
}
λ°λ³΅ν΄μ λ§νμλ©΄, μλ΅ λ΄μ©μ μν μ½λλ₯Ό λ°λμ λ£μ΄μΌ ν νμλ μμ§λ§ book/not_found
μ κ°μ μ체 μ€λ₯ μ½λλ₯Ό μ μνλ κ²μ ν΄λΌμ΄μΈνΈ μ
μ₯μμλ λ§€μ° μ μ©νλ€. νΉν κ°λ° νκ²½μμλ μλ¬ μ€νμ μλ΅μ ν¬ν¨μμΌ λ²κ·Έλ₯Ό λλ²κΉ
νλ κ²μ΄ μ μ ν μ μλ€. λ¬Όλ‘ νλ‘λμ
νκ²½μμλ μλ¬ μ€νμ λ
ΈμΆ μν΄μΌλ‘ 보μ λ¬Έμ λ₯Ό μ΄λν μ μμΌλ―λ‘ μ΄λ¬ν μ 보λ₯Ό λ°°μ ν΄μΌ νλ€.
5. μλ΅ κ°μΌλ‘ 컬λ μ μ λ°μΌλ©΄ νμ΄μ§κ³Ό νν°λ§, μ λ ¬ μ²λ¦¬λ₯Ό ν΄μΌνλ€.
μλ΅ κ°μΌλ‘ 리μ€νΈλ₯Ό λ°λ endpoint λ₯Ό μ€κ³ν λ νμ΄μ§ μ²λ¦¬λ₯Ό ν΄μ€μΌ νλ€. μμ€ν μ΄ λ°μ ν¨μ λ°λΌ 컬λ μ κ°λ κ·λͺ¨κ° μ μ°¨ 컀μ§κΈ° λλ¬Έμ, νμ μ ν΄μ§ μμ λ°μ΄ν°λ₯Ό λ°ννλλ‘ μ μ΄ν΄μΌ νλ€. λ¬Όλ‘ ν΄λΌμ΄μΈνΈ μΈ‘μμ μ λ¬λ°μ λ°μ΄ν°μ κ·λͺ¨λ₯Ό μ νλ κ²μ΄ 곡μ νκ² μ§λ§, API μΈ‘μμ 미리 κ·Έ κ·λͺ¨μ μ΅λ κ°μ κ·μ ν΄ λλ κ²μ΄ μ’λ€. μ΄λ° νμ΄μ§ μ²λ¦¬λ₯Ό νλ μ΄μ λ, λ°©λν μμ λ°μ΄ν° λ°°μ΄μ λ°ννλ λ° λ§μ μκ°κ³Ό λμνμ΄ μλͺ¨λκΈ° λλ¬Έμ΄λ€ .
skip/limit
κ³Ό keyset
μ΄ λνμ μΈ νμ΄μ§ μ²λ¦¬ κΈ°λ²μ΄λ€. skip/limit μ΅μ
μ λ°μ΄ν°λ₯Ό κ°μ Έμ€λ μ΅μν λ°©λ²μ μνμ§λ§, ν
μ΄λΈ νλ°λΆμ μμΉν λ°μ΄ν°λ₯Ό κ°μ Έμ¬ λ μκ°μ΄ λ§μ΄ μλͺ¨λκΈ° λλ¬Έμ μΌλ°μ μΌλ‘ μ±λ₯μ΄ λ¨μ΄μ§λ€. λ°λ©΄ keyset νμ΄μ§ κΈ°λ²μ μλ³μ/IDλ₯Ό μ°Έμ‘°κ°μΌλ‘ λ°μ 리μ€νΈλ ν
μ΄λΈμ μ€μΊν νμμμ΄ μ‘°κ±΄μ λ°λΌ λ°μ΄ν°λ₯Ό νμ΄μ§ν μ μλ€.
λμΌν μΈ‘λ©΄μμ, API λ λ°μ΄ν°λ₯Ό μ‘°νν λ νν°μ μ λ ¬ κΈ°λ₯λ μ 곡ν΄μΌ νλ€. μ±λ₯ ν₯μμ μν΄ DB μΈλ±μ€λ νν°μ μ λ ¬μ ν΅ν΄ μ μ©λλ Access ν¨ν΄μ μ¬μ©νκΈ°λ νλ€. APIλ₯Ό μ€κ³ν λ νν°μ μ λ ¬μ 쿼리 νλΌλ―Έν°μ μ μλλ€. μλ₯Ό λ€μ΄ "romance" λ²μ£Όμ μνλ μ΄κΈ° 10κΆμ μ± μ μ‘°ννλ €λ©΄ μλν¬μΈνΈλ μλμ²λΌ μ€κ³ν΄μΌνλ€.
GET /books?limit=10&category=romance
6. PUT λμ PATCH μ μ¬μ©νλΌ .
μν°ν°μ λͺ¨λ μνκ°μ νλ²μ μμ νλ μΌμ νν μΌμ΄λμ§ μλλ€. λν ν΄λΌμ΄μΈνΈκ° μμ νμ§ λͺ»νκ² μ μ§νκ³ μΆμ 볡μ‘νκ±°λ λ―Όκ°ν λ°μ΄ν°λ μ‘΄μ¬νκΈ° λ§λ ¨μ΄λ€. PUT λ©μλλ 리μμ€μ λͺ¨λ μμλ₯Ό μμ ν΄λ²λ¦¬κΈ° λλ¬Έμ, λ°μ΄ν°μ λΆλΆμ μΈ μμ μ΄ νμν λ PATCH λ©μλλ₯Ό μ¬μ©νλ€. λ λ©μλ λͺ¨λ μ λ°μ΄νΈ ν΄μΌνλ μ 보λ₯Ό HTTP Body μ λ΄μ 보λ΄μΌνλ€.
νμ§λ§ κ·Έλ λ€κ³ νμ¬ λΆλΆ μ λ°μ΄νΈλ₯Ό ν λ PUT λ©μλλ₯Ό μμ μ¬μ©νμ§ λ§λΌκ³ κ°μ ν μλ μλ λ Έλ¦μ΄λ€. μ ν΄μ§ "λ€νΈμν¬ μ μ‘ μ ν" κ·λ²μ΄ μλ κ²λ μλλ©°, κ·Έμ PATCH λ©μλλ₯Ό μ¬μ©νλ κ²μ΄ μ’μ λ°©λ²μ΄λΌ κΆμ₯λ λΏμ΄λ€.
7. νμ₯λ μλ΅ μ΅μ μ μ 곡νλΌ.
μμ€ν μ΄ νμ₯λ¨μ λ°λΌ, μλ΅ κ°μ νλ‘νΌν°κ° λμ΄λ μ λ μμ§λ§, ν΄λΌμ΄μΈνΈμκ² λͺ¨λ νλ‘νΌν°κ° νμνμ§ μμ μ μλ€. μ΄λ° κ²½μ°μλ λμΌν μλν¬μΈνΈμ
1) νμν νλ‘νΌν°λ§ μ 곡νλ μΆμλ μλ΅ ν¬λ§·μ λ΄λ €μ£Όκ±°λ
2) μΆμνμ§ μμ κΈ°μ‘΄ μλ΅ ν¬λ§·μ λ΄λ¦¬λ
2κ°μ§ μ νκΆμ μ€ μ μλ€.
ν΄λΌμ΄μΈνΈκ° μλ΅ κ°μ μΌλΆλ§ νμλ‘ ν λ, κ°λ΅νλ μλ΅ ν¬λ§·μ λ΄λ¦¬λ κ²μ΄ λμν λλΉλ₯Ό μ€μΌ μ μλ€.
μλ μμμ²λΌ exteneded λΌλ μΆκ° 쿼리λ₯Ό λ§€κ° λ³μλ‘ μ 곡νλ©΄ νμ₯λ μλ΅ μ 곡μ μ½κ² νμ±/λΉνμ±ν ν μ μλ€.
GET /books/:id
{
"bookId": 1,
"name": "The Republic"
}
GET /books/:id?extended=true
{
"bookId": 1,
"name": "The Republic"
"tags": ["philosophy", "history", "Greece"],
"author": {
"id": 1,
"name": "Plato"
}
}
8. μλν¬μΈνΈμ μ± μμ μκ°νλΌ
API κ° νλμ μμ μ μ μννλ λμμ λ³νμ§ μλλ€λ©΄, ν΄λΉ APIλ μ μ€κ³λ κ²μ΄λΌ ν μ μλ€. μ μ€κ³λ API λ ν΄λΌμ΄μΈνΈκ° API λ₯Ό μ½κ² μ΄ν΄νκ³ , μ λ°μ μΈ ν΅ν©μ μ©μ΄νκ² νμ¬ μμΈ‘ κ°λ₯νκ² λ§λ λ€. νλ²μ λ§μ μμ μ ν΄κ²°νλ 볡μ‘ν μλν¬μΈνΈλ₯Ό ꡬμΆνλ κ² λ³΄λ€, μ¬μ© κ°λ₯ν μλν¬μΈνΈ λͺ©λ‘μ μ 체μ μΌλ‘ νμ₯νλ κ²μ΄ λ°λμ§νλ€.
9. μ νν API λ¬Έμλ₯Ό μ 곡νλΌ.
APIλ₯Ό μ μ 리ν λ¬Έμκ° μμ΄μΌ ν΄λΌμ΄μΈνΈλ μ¬μ©κ°λ₯ν μλν¬μΈνΈλ₯Ό μ΄λ»κ² μ¬μ©ν κ²μ΄λ©°, μ΄λ€ κ²°κ³Όλ₯Ό λ°μ μ μμμ§ μμΈ‘ν μ μλ€.
μ 리λ λ¬Έμλ₯Ό μ 곡νκΈ° μν΄μ λ€μκ³Ό κ°μ μΈ‘λ©΄μ κ³ λ €ν΄μΌ νλ€.
- μλν¬μΈνΈμ λͺ©μ μ μ€λͺ
- μλν¬μΈνΈλ₯Ό μ€νν λ νμν κΆν
- νΈμΆ λ° μλ΅ μμ
- μμ μ€λ₯ λ©μμ§
μμ€ν μ΄ μ λ°μ΄νΈ λκ³ λ³κ²½λ λ λ§λ€ API λ¬Έμ μμ μ λ°μ΄νΈ ν΄μ£Όλ κ²μ΄ μ€μνλ€. μ΄λ₯Ό μ§ν¬ μ μλ κ°μ₯ μ’μ λ°©λ²μ API λ¬Έμνλ₯Ό κ°λ°μ κΈ°λ³ΈμΌλ‘ μΌλ κ²μ΄λ€. Swaggerμ Postmanμ΄ μ μλ €μ§ API λ¬Έμν λκ΅¬λ‘ λλΆλΆμ API κ°λ° νλ μμν¬μμ μ¬μ©ν μ μλ€.
10. 보μμ μν SSL μ¬μ© λ° CORS μ€μ
보μ μμ APIκ° κ°μΆ°μΌ ν κΈ°λ³Έμ μΈ μμ± μ€ νλλ€.
μλ²μ μ ν¨ν μΈμ¦μλ₯Ό μ€μΉνμ¬ SSL μ μ€μ νλ©΄, ν΄λΌμ΄μΈνΈμμ μμ ν ν΅μ μ 보μ₯νκ³ λͺ κ°μ§ μ μ¬μ μΈ κ³΅κ²©μ λ°©μ§ν μ μλ€.
CORS(Cross Origin Resource Sharing)
λ λΈλΌμ°μ 보μ κΈ°λ₯μΌλ‘, λΈλΌμ°μ μ μ€ν¬λ¦½νΈμμ μμλλ ν¬λ‘μ€ μ€λ¦¬μ§(Cross origin) HTTP μμ²μ μ ννλ€. 볡μ‘ν ν¬λ‘μ€ μ€λ¦¬μ§ HTTP μμ²μ μμ νλ REST APIλ, κ·Έμ λμν μ μλ CORS μ§μμ νμ±ν ν΄μΌ νλ€.
CORS νλ‘ν μ½μ λΈλΌμ°μ κ° μλ²μ μ¬μ μμ²preflight
μ 보λ΄λλ‘ νλ©°, μ€μ μμ²μ 보λ΄κΈ° μ κΉμ§ μλ²μ μΉμΈμ κΈ°λ€λ¦°λ€. μ¬μ μμ²(preflight request)μ OPTIONS λ©μλλ₯Ό μ¬μ©νλ HTTP μμ²μ μλ―Ένλ€. μ¦ REST APIκ° CORSμ λμνλ €λ©΄ μ¬μ μμ²(preflight)μ OPTIONS λ©μλλ₯Ό μνν μ μλλ‘, FETCH νμ€μμ μꡬνλ μλμ μ¬νμ μλ΅ ν€λμ λ£μ΄μΌνλ€.
- Access-Control-Allow-Methods
- Access-Control-Allow-Headers
- Access-Control-Allow-Origin
μ 3κ°μ§ key κ°μ ν λΉλ κ°μ API κ° μΌλ§λ κ°λ°©μ μ΄κ³ μ μ©νμ§μ λ°λΌ λ¬λΌμ§λ€. μ μλ €μ§ Origin μ ν λΉνκ±°λ μμΌλ μΉ΄λλ₯Ό μ¬μ©νλ λ°©λ² λ±μΌλ‘ CORS λ₯Ό μ€μ ν μ μλ€.
11. API λ²μ
κ°λ° νλ‘μΈμ€μ μΌνμΌλ‘, API μλν¬μΈνΈκ° λ³κ²½λκ±°λ μ¬κ΅¬μΆ λλ κ²½μ°κ° μλλΌλ, ν΄λΌμ΄μΈνΈ ν΅μ μ μν΄ κ°μκΈ° μλν¬μΈνΈλ₯Ό λ³κ²½νλ μΌμ νΌν΄μΌνλ€. APIλ μλ‘μ΄ μλν¬μΈνΈκ° μ΄μ λ²μ μ νμ€μ μν₯μ μ£Όμ§ μλ νμ νΈν 리μμ€λ‘ μκ°νλ κ²μ΄ λ°λμ§νλ€. ν΄λΌμ΄μΈνΈλ μμ μ΄ μμ²ν API μ£Όμλ₯Ό μ νν μ μμ΄μΌνκ³ , μλμ²λΌ API λ²μ μ κ΄λ¦¬νλ μ¬λ¬ λ°©λ²μ΄ μλ€ .
1. μλ‘μ΄ ν€λ μΆκ° "x-version=v2"
2. 쿼리 νλΌλ―Έν° μ¬μ© "?apiVersion=2"
3. URLμ μΌλΆλ‘ λ²μ μ νκΈ° "/v2/books/:id"
12. μ±λ₯ ν₯μμ μν μΊμ λ°μ΄ν° νμ©
API μ μ±λ₯ ν₯μμ λμ΄λ €λ©΄ λΉλ²ν μ¬μ©λλ©°, μ½κ² λ³νμ§ μλ λ°μ΄ν°λ₯Ό μΊμ±ν΄λλ κ²μ΄ μ’λ€. μ κ·Ό λΉλκ° λμ λ°μ΄ν°λ₯Ό μ νμ©νλ €λ©΄, μΈλ©λͺ¨λ¦¬λ μΊμ λ°μ΄ν°λ² μ΄μ€λ₯Ό μ¬μ©νμ¬ λ©μΈ λ°μ΄ν°λ² μ΄μ€μ μ κ·Όνλ λΉμ©μ μ€μ΄λ λ°©λ²μ κ³ λ €ν μ μλ€. μΊμ±λ λ°μ΄ν°κ° outdated λ μ μμΌλ―λ‘ μ΅μ μνμ λ°μ΄ν°λ‘ κ΅μ²΄ νλ λ°©λ² μμ κ³ λ―Όν΄μΌ νλ€.
ν΄λΌμ΄μΈνΈ μ
μ₯μμλ, μ€μ μ΄λ μΉ΄νλ‘κ·Έ μ 보 μ²λΌ μκ°μ΄ μ§λλ μ λ³νμ§ μλ μ 보λ₯Ό μΊμ λ°μ΄ν°λ‘ νμ©νλ©΄ λ§€μ° μ μ©νλ€. μΊμ λ°μ΄ν°λ₯Ό μ¬μ©ν λ HTTP ν€λμ Cache-Control
νλ‘νΌν°λ₯Ό κΌ ν¬ν¨ν΄μΌ νλ€.
13. νμ€ UTC μ¬μ©
λ°μ΄ν° μμ€μμ ν΄λΌμ΄μΈνΈ μΈ‘μ λ μ§ νμ€ λ°©μμ μΌκ΄μ± μκ² λ³΄μ¬μ£Όλλ‘ μ μ§νλ μΌμ μ€μνλ€. ISO 8601 λ λ μ§/μκ° λ°μ΄ν°μ κ΅μ νμ€ νμμΌλ‘, λ μ§λ 'Z' λλ UTC νμμ΄μ΄μΌ νλ©°, ν΄λΌμ΄μΈνΈλ μ΄λ€ 쑰건μμλ ν΄λΉ λ μ§λ₯Ό νμν΄μΌ ν κ²½μ° μκ°λλ₯Ό κ²°μ ν μ μλ€.
λ€μμ λ μ§ νμμ μμλ₯Ό 보μ¬μ€λ€.
{
"createdAt": "2022-03-08T19:15:08Z"
}
14. ν¬μ€ μ²΄ν¬ μλν¬μΈνΈ
API μ λ¬Έμ κ° μ겨 λ€μ΄λ λ, API λ₯Ό μ¬κ°λνκ³ μ€ννλλ° μκ°μ΄ 걸릴 μ μλ€. μ΄λ¬ν μν©μμ ν΄λΌμ΄μΈνΈλ λ¬Έμ μν©μ νμ νκ³ κ·Έμ λ°λΌ μλΉμ€λ₯Ό μ΄μ©ν μ μλ€λ μ¬μ€μ μμμΌ νλ€. μ΄λ₯Ό μν΄ API κ° μ μμ μΌλ‘ λμνλμ§ νμΈν μ μλ μλν¬μΈνΈ (ex GET /health) λ₯Ό μ 곡ν΄μΌνλ€. μ΄λ° μλν¬μΈνΈλ λ‘λλ°Έλ°μ κ°μ λ€λ₯Έ μ΄ν리μΌμ΄μ μ μν΄ νΈμΆλ μ μμΌλ©°, λ λμκ° APIμ ν¬μ€ 체ν¬λ μ μ§ λ³΄μ κΈ°κ°μ μλ €μ€ μλ μλ€.
15. API Key μΈμ¦μ νμ©νλΌ
API key λ₯Ό ν΅ν μΈμ¦μ μ¨λ νν° μ΄ν리μΌμ΄μ μ΄ μ°λ¦¬μ APIμ μμ½κ² μ¬μ©λλλ‘ λ§λ€ μ μλ€. API key κ°μ X-Api-Key λ Api-Key κ°μ 컀μ€ν HTTP ν€λλ₯Ό ν΅ν΄ μ λ¬λΌμΌ νλ€. Keyμ λ§λ£ κΈ°ν μμ μ§μ λΌμΌ νλ©°, 보μμ λ¬Έμ κ° μμ λ 무ν¨ν λλλ‘ ν΄μ§ν μ μμ΄μΌ νλ€.
'π Web' μΉ΄ν κ³ λ¦¬μ λ€λ₯Έ κΈ
Refresh Token Rotation κ³Ό Redisλ‘ ν ν° νμ·¨ μλλ¦¬μ€ λμ (9) | 2023.04.21 |
---|---|
Web Server μ WAS λ₯Ό μμ보μ (1) | 2022.12.24 |
ν¬μλ νλ‘μ μ 리λ²μ€ νλ‘μ (forward proxy, reverse proxy) (1) | 2021.08.24 |
HTTP 401(Unauthorized), 403(Forbidden) μ°¨μ΄ (0) | 2021.06.20 |
7. HTTP ν€λ 2 - μΊμμ μ‘°κ±΄λΆ μμ² (2) | 2021.01.17 |