학교에서 알려주지 않는 17가지 실무 개발 기술 15장

💡 필자가 책을 읽고, 몰랐던 부분이나, 특별히 메모할만한 내용을 추출하여 기록한 포스팅입니다. 책 내용 외에 추가 설명을 덧붙인 부분들이 있습니다

---

[학교에서 알려주지 않는 17가지 실무 개발 기술] 구매하러 가기 ⬇

학교에서 알려주지 않는 17가지 실무 개발 기술:문자열 인코딩부터 웹 필수 지식까지

"이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다."

---

이전 포스팅(⬇)에서 이어집니다.

[책장파먹기] HTTP: 학교에서 알려주지 않는 17가지 실무 개발 기술 14장

RESTful

representational state transfer 의 약자 - 분산시스템을 위한 아키텍처의 한 형태

API 설계를 할 때는 다음과 같은 API 디자인 가이드를 참고하는 것이 좋음

https://docs.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

웹 API 디자인 모범 사례 - Azure Architecture Center

Control URI

http://localhost:5000/v1/write_posts 와 같은 객체의 행동을 주소에서 정의하는 URL 이 좋지 않은 이유

• Http 메서드(GET, POST, PUT, DELETE 등)의 역할이 축소된다.
• 다른 행동에 대한 요청 주소가 바뀔 때마다 모두 기억하는 건 어렵다.

💡 하지만 이러한 URL 을 사용해야만 하는 경우도 분명 생길 수 있다. 이런 형태를 ‘컨트롤 URI 라고 한다. 즉, 모든 API 를 RESTful 하게 짜야만 한다는 강박은 갖지 않아도 된다. 참고: 모든 개발자를 위한 HTTP 웹 기본 지식

url-safe encoding

URL 에는 ASCII 코드의 값만을 허용한다. 따라서 base64 로 변환해주는 과정이 반드시 필요하다. 그런데, ? 이나 = , & 등의 문자들은 예약어로 사용되기 때문에 url-safe base64 인코딩을 활용하여 인코딩해주어야 한다. 이를 활용하면= 같은 경우에는 %3D 로 인코딩된다.

확장성을 고려한 API 응답 본문 인터페이스

글을 불러오는 API 를 설계한다고 가정하자. 다음과 같이 글 목록을 불러오는 API 가 있고, 단일 글을 불러오는 API 가 있다.

/v1/posts?page=1&size=10: 글 목록 불러오기

/v1/posts/<글 번호>: 단일 글 불러오기

이 두 API 의 응답은 같은 인터페이스로 설계할 수 있다. 이를 JSON 으로 표현하면 다음과 같다.

{
    "posts": [
        {
            "title": "블로그 제목",
            "contents": "...",
            "date": "2020-10-10...",
            "number": 12
        }
    ],
    "error": {
        "code": 42101,
        "message": "올바르지 않은 단어가..."
    }
}

위 API 응답 본문은 두 가지를 고려한 설계의 결과이다.

• 데이터영역과 에러처리영역을 구분하여, 클라이언트가 메시지를 해석하기 용이하게 설계하였다.
• posts 는 배열의 형태로 설계하여, 단건과 다건 조회 모두에 대응될 수 있도록 설계하였다.

RESTful 에 관하여

• RESTful 이란 정답이라기보단 관례에 가깝다.
• 실무의 API 는 ‘일관성’을 지키는 것이 매우 중요하다. 특히 공개 API 인 경우 더더욱 그렇다.
• API 설계는 API 를 사용하는 사용자 입장에서 생각해야 한다.
• 공개 API 를 설계해야한다면, OpenAPI 2.0 / 3.0 이나, Azure API 디자인 가이드 문서를 표준으로 삼는 것이 좋다.

---

[학교에서 알려주지 않는 17가지 실무 개발 기술] 구매하러 가기 ⬇

학교에서 알려주지 않는 17가지 실무 개발 기술:문자열 인코딩부터 웹 필수 지식까지

"이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다."

---