반응형
1. API 연동 기본 개념
API(Application Programming Interface)는 시스템 간 데이터 및 기능을 교환하는 인터페이스야. API 연동은 주로 REST API, GraphQL, gRPC 방식이 사용돼.
1) API 연동 방식
✅ REST API (Representational State Transfer)
- HTTP 기반, 가장 널리 사용됨
- 리소스를 GET, POST, PUT, DELETE 메서드로 조작
✅ GraphQL
- 클라이언트가 원하는 데이터만 요청 가능
- REST보다 네트워크 사용량 절감 가능
✅ gRPC
- HTTP/2 기반, 바이너리 포맷 사용 → 빠른 성능
- 대규모 분산 시스템에서 사용 (ex: 마이크로서비스)
2. API 설계 원칙 (Best Practices)
1) RESTful API 설계 원칙
✅ 1. 리소스 중심의 URL 설계
- 좋은 예
GET /users/{id} → 특정 사용자 조회
POST /users → 사용자 생성
PUT /users/{id} → 사용자 수정
DELETE /users/{id} → 사용자 삭제- 나쁜 예
GET /getUser?id=123 → 동사 사용 ❌✅ 2. HTTP 상태 코드 활용
상태 코드설명
| 200 OK | 정상 처리 완료 |
| 201 Created | 리소스 생성 성공 |
| 400 Bad Request | 잘못된 요청 |
| 401 Unauthorized | 인증 실패 |
| 403 Forbidden | 권한 없음 |
| 404 Not Found | 리소스 없음 |
| 500 Internal Server Error | 서버 오류 |
✅ 3. HATEOAS 적용
- API 응답에 관련된 링크 포함 → 클라이언트가 API 흐름을 쉽게 이해 가능
{
"id": 123,
"name": "John Doe",
"links": [
{ "rel": "self", "href": "/users/123" },
{ "rel": "orders", "href": "/users/123/orders" }
]
}✅ 4. API 버전 관리
- API 변경 시 클라이언트가 영향을 받지 않도록 버전 관리 필수
- URL 또는 Accept 헤더로 버전 제공
GET /v1/users/{id}
GET /users/{id} (헤더 `Accept: application/vnd.company.v1+json`)3. API 연동 시 자주 하는 실수 & 해결 방법
1) 인증 & 보안 문제
✅ 실수 1: API Key 또는 토큰을 하드코딩
- 잘못된 예:
String apiKey = "1234567890abcdef"; // ❌ API 키 하드코딩 - 해결 방법:
- 환경 변수, .properties 파일, AWS Secrets Manager 등을 사용하여 API 키 보관
String apiKey = System.getenv("API_KEY"); // ✅ 안전한 API 키 관리✅ 실수 2: HTTPS 미사용
- 해결 방법:
- API 서버는 반드시 HTTPS(SSL/TLS) 적용
- 클라이언트 요청 시 HTTP가 아닌 HTTPS 사용
✅ 실수 3: CORS 정책 미설정
- 해결 방법:
- 필요한 출처(Origin)만 허용 (Access-Control-Allow-Origin)
- Spring Boot에서 CORS 설정 예제
@Configuration
public class CorsConfig {
@Bean
public WebMvcConfigurer corsConfigurer() {
return new WebMvcConfigurer() {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
.allowedOrigins("https://trusted.com") // 특정 도메인만 허용
.allowedMethods("GET", "POST");
}
};
}
}2) 요청 & 응답 처리 문제
✅ 실수 4: 요청 타임아웃 미설정
- 해결 방법:
- HttpClient 또는 RestTemplate의 타임아웃 설정
- 네트워크 지연을 고려하여 적절한 타임아웃 값 설정
RestTemplate restTemplate = new RestTemplate();
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
factory.setConnectTimeout(5000); // 5초 타임아웃
factory.setReadTimeout(5000);
restTemplate.setRequestFactory(factory);✅ 실수 5: 응답 데이터 검증 안 함
- 해결 방법:
- JSON 응답 데이터를 객체 매핑 후 검증
- @Valid 어노테이션 사용하여 데이터 유효성 검사
public class UserResponse {
@NotNull private Long id;
@NotBlank private String name;
}✅ 실수 6: 예외 처리 부족
- 해결 방법:
- API 요청 시 try-catch로 예외 처리
- @ControllerAdvice를 사용하여 예외 핸들링
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(HttpClientErrorException.class)
public ResponseEntity<String> handleClientError(HttpClientErrorException e) {
return ResponseEntity.status(e.getStatusCode()).body("Client Error: " + e.getMessage());
}
}3) 성능 최적화
✅ 실수 7: API 호출 최적화 부족
- 해결 방법:
- API 응답을 캐싱하여 반복 요청 최소화 (Redis 활용)
- ETag 및 Last-Modified 헤더를 사용하여 불필요한 데이터 전송 방지
✅ 실수 8: 대량 데이터 전송
- 해결 방법:
- 페이징 적용 (limit & offset 사용)
- 대량 데이터를 배치 요청으로 분할하여 처리
GET /users?page=1&size=20 // ✅ 페이징 적용✅ 실수 9: 불필요한 필드 전송
- 해결 방법:
- GraphQL을 사용하여 필요한 데이터만 요청
- REST에서는 DTO를 사용하여 필요한 데이터만 반환
public class UserDTO {
private Long id;
private String name;
}4. API 테스트 & 문서화
✅ Postman / Swagger 사용
- API 테스트 및 문서화 도구 활용
- Spring Boot에서는 Springdoc OpenAPI 또는 Swagger 사용
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.api"))
.paths(PathSelectors.any())
.build();
}
}- http://localhost:8080/swagger-ui/ 접속하여 API 확인 가능
결론
API 연동을 안정적으로 하려면 아래 사항을 고려해야 해.
✅ 보안 → 인증(토큰, OAuth), HTTPS 사용, API 키 관리
✅ 요청 최적화 → 타임아웃 설정, 페이징, 캐싱 활용
✅ 에러 핸들링 → 예외 처리, HTTP 상태 코드 활용
✅ 성능 최적화 → 최소한의 데이터 전송, 배치 요청
✅ API 문서화 → Swagger, Postman 사용