좋은 API 란?

Younghwan Cha·2022년 5월 11일
0

Web

목록 보기
2/15
post-thumbnail

좋은 api, 잘 만든 api 란 무엇일까?
REST api, CRUD, HTTP Method 등등 api 과 관련한 이야기를 해보자

먼저, 좋은 api 는 과연 무엇일까?
에러가 없는 것은 기본이거니와 그 목적을 잘 달성하면 되겠다
그 목적이 무엇일까?
api의 사용자는 고객뿐만 아니라 우리 개발자도 포함된다.
그렇기 때문에 문제가 생겼을 때 로그 및 에러 처리를 해두는 것도 중요하다

오류가 명시적인 API

많은 사람들이 API 기능 자체에만 신경을 쓰고 오류 모드에 대해서는 무관심한 경향이 있다.
하지만, 차후 일어날 문제들에 빠르게 대처하기 위해서는 API 응답 결과에서 명시적으로 알려주는 것이 좋습니다.

바로 목적과 사용법을 이해할 수 있는 API

좋은 API 는 문서화가 잘 된 것이 아니라 문서를 읽지 않더라도 그 API 자체가 그 기능을 설명할 수 있도록 설계해야
좋은 API 이다. 또한 호출 결과에 그 다음에 사용할 만한 해당 API 기능에 대한 명시적인 설명이 있어도 좋다.

구현 세부 정보는 비밀

위와 반대되게 목적은 분명히 하되 그 세부 구현 사항들은 가급적 누출되지 않도록 해야한다. API 의 내부 구조에 대한 단서를 알게되면 보안 이슈를 만들 수도 있기 때문이다.


resource 를 명사로 표현

URI 를 동사가 아닌 명사로 표현해야 한다.
또한, snake_case, camelCase, hyphenated 등을 통해서 명사와 동사를 함께 사용하는 것을 지양해야한다.

http://api.example.com/v1/store/CreateItems/{item-id}❌
http://api.example.com/v1/store/getEmployees/{emp-id}❌
http://api.example.com/v1/store/update-prices/{price-id}❌
http://api.example.com/v1/store/deleteOrders/{order-id}❌

http://api.example.com/v1/store/items/{item-id}✅
http://api.example.com/v1/store/employees/{emp-id}✅
http://api.example.com/v1/store/prices/{price-id}✅
http://api.example.com/v1/store/orders/{order-id}✅

resource 를 복수명사로 표현

resource 객체의 인스턴스가 오직 1개만 생성되는 singleton resource 일 경우를 제외하고는 가능한 복수 명사를 사용하는 것이 좋다.

http://api.example.com/v1/store/item/{item-id}❌
http://api.example.com/v1/store/employee/{emp-id}/address❌

http://api.example.com/v1/store/items/{item-id}✅
http://api.example.com/v1/store/employees/{emp-id}/address✅

[ref][RESTful API] https://medium.com/@nadinCodeHat/rest-api-naming-conventions-and-best-practices-1c4e781eb6a5
https://aws.amazon.com/ko/blogs/korea/werner-vogels-lesson-learned-for-good-api-design/

profile
개발 기록

0개의 댓글