웹 사이트 서버와 모바일 앱 API 서버는 기술적인 부분에서 비슷한 부분이 많지만 앱 API 서버라는 특성 때문에 조금 신경 써야할 부분도 있기에 API 디자인 시 참고할 만한 내용들을 찾아보고 정리한 내용이다.
API 서버는 한번 API가 클라이언트에게 나가고 나면 변경하기가 힘들다.
웹 사이트는 클라이언트 코드와 서버 코드 모두 웹 서버에서 제공하기 때문에 두 부분을 동시에 변경하는 것이 가능하지만,
앱 같은 경우에는 일반적으로 앱 스토어를 통해서 배포되기 때문에 동시에 변경할 수도 없고
사용자가 업데이트 하지 않으면 계속해서 구 버전을 사용할 수도 있다. 앱을 업데이트하지 않으면 사용할 수 없도록 강제 업데이트하는 방법이 있긴 하지만 되도록이면 피해야 한다.
REST를 준수하는 것은 좋지만 그것을 목표로 해야하는 것은 아니다.
API 페이로드를 디자인할 때 일관성, 완성도에 신경을 쓰도록 하라.
일관성은 API를 사용하는 개발자가 무엇을 기대해야 할지 아는 것이다. (가장 적게 놀람의 원칙)
완성도는 적은 roundtrip을 의미한다. 3G 환경에서 HTTP latency는 1초까지 걸릴 수 있다.
API는 DB에 대한 CRUD 인터페이스가 아니다.
더 높은 추상 레벨의 Facade이다. 객체나 메소드가 아닌 서비스 관점에서 생각해야 한다.
그러면 어떻게 시작해야 하는가? 대부분의 모바일 API는 화면에 보여줄 정보를 가져오기 위해 사용된다. 데이터로부터가 아니라 UI에서부터 시작해야 한다.
1. 화면을 구상한다.
2. 보여줄 엔티티들은 무엇인지
3. 엔티티 모델을 디자인한다.
4. 서비스를 디자인한다.
일관성있게 데이터를 제공한다.
"person": {
"id": 1234,
"name": "Fred",
"lastname": "Brunel"
}
<좋지 않은 예>
"book": {
"Name": "Steve Jobs",
"author": "Walter",
"lenders": = [{
"person_id": 1234,
"person_name": "Fred",
"person_lastname": "Brunel"
}]
}
<좋은 예>
"book": {
"name": "Steve Jobs",
"author": "Walter",
"lenders": = [{
"id": 1234,
"name": "Fred",
"lastname": "Brunel"
}]
}
대부분의 일반적인 항목들을 정규화 하라.
불필요한 요청을 하지 않아도 되게 하자.
<좋지 않은 예>
"result": {
"categories": [{ "id: 2 }],
"images": [{ "id": 2323 }]
}
<좋은 예>
"result": {
"categories": [{
"id: 2,
"name": "food"
}],
"images": [{
"id": 2323,
"url": "http://image.com/a.png"
}]
}
예를 들어 사용자가 어떤 데이터를 요청하기 전에 로그인을 해야한다고 하자. 다음 두 단계로 진행하는 방법을 생각해볼 수 있다.
1. 클라이언트로부터 인증 정보가 제공되고 유효하다면 API로 세션 토큰을 전달한다.
2. 클라이언트가 세션 토큰과 함께 데이터 요청을 한다
하지만 클라이언트가 인증 정보와 데이터 요청을 함께 보내고 서버는 데이터와 세션 토큰을 전달함으로써 한번의 요청만 하는 방법도 있다.
이렇게 하면 두 가지 사용법을 모두 지원할 수 있도록 개발해야해서 유지보수 비용이 더 발생할 수 있다. 하지만 만약 본인이 사용하기 위한 API를 개발하는 것이라면 좀 더 적용할만 하다.
앱에서 다른 써드파티 시스템들과 연동하게 하지말고 서버에서 취합하는 방식을 사용해라.
서버가 더 많은 배터리와 대역폭 그리고 데이터들을 가지고 있다.
빠르게 만들어라.
- 배치 요청: 복수 operation들을 보내고 한번에 결과를 받는 방법
- 네트워크가 중요하다면 별도 프로토콜을 정의하는 방법: HTTP 프토코콜 대신 별도의 Binary 프로토콜을 만든다.
버저닝을 하는 것에 대한 고려
웹 기반의 앱은 버저닝이 크게 중요하지 않지만 네이티브 앱은 중요한 문제이다. API의 기능이 추가, 변경, 삭제되는 일이 발생하게 되는데 버저닝을 통해서 구버전 API를 사용하는 앱에서도 호환성을 지킬 수 있다.
여러 자료들을 본 결과 버저닝이 필요한 것인지, 버저닝에 자유로운 API를 만드는게 좋은지에 대한 논란이 분분한 것 같다.
만약 버저닝을 한다면 다음 정도의 방법이 있다.
[버저닝 방법]
- url path parameter
- url parameter
- Http Accept header
이름을 신중하게 지어라.
API의 프로퍼티, 파라미터, 메소드의 이름은 클라이언트가 API를 이해하는데 많은 영향을 준다. 실제 코드가 어떠하든, API를 이해하고 동작을 예상하는데 이름을 큰 영향을 준다. 잘못된 이름은 혼동을 주고 혼동은 실수를 유발하며 실수는 버그를 만든다.
[참고자료]
'개발' 카테고리의 다른 글
| 카프카, 데이터 플랫폼의 최강자 - 2장 카프카 설치 (0) | 2020.08.26 |
|---|---|
| 카프카, 데이터 플랫폼의 최강자 - 1장 카프카란 무엇인가 (0) | 2020.08.24 |
| 클린 코더 - 1장 프로의 마음가짐 (0) | 2017.10.20 |
| 실용주의 디버깅 - 2부 큰 그림 (2) | 2016.10.18 |
| 실용주의 디버깅 - 1부 문제의 핵심 (2) | 2016.10.17 |