RESTful API란? 정의 및 장, 단점 (+ Java SpringBoot 메모장 API 예제)

RESTful API란?

RESTful API는 웹 서비스에서 클라이언트와 서버간에 통신을 용이하게 하기 위해 개발된 인터페이스입니다. REST(Representational State Transfer) 원리를 따른다는 의미로 “RESTful하다.” 라고 말할 수 있으며 이런 RESTful한 API를 가리켜 RESTful API라고 할 수 있습니다. RESTful API는 자원을 URI(Uniform Resource Identifier)로 표현하고 CRUD(Create, Read, Update, Delete) 기능을 HTTP 메소드로 사용합니다.

RESTful API의 구성요소

RESTful API는 다음과 같은 구성요소를 가지고 있습니다.

Resource: 웹상의 자원은 URI로 표현됩니다. 이 URI는 고유한 리소스를 가리키며, 클라이언트는 이를 이용하여 작업을 수행합니다.
Method: 리소스에 대한 액션은 HTTP 메소드를 이용하여 나타냅니다. 주로 사용되는 메소드는 GET, POST, PUT, DELETE입니다.
Representation: 리소스의 상태는 JSON, XML 등의 형태로 교환됩니다. 클라이언트와 서버는 독립적이기 때문에, 서로 통신의 규약을 알고 있어야 합니다.

RESTful API의 장단점

RESTful API의 장단점은 아래와 같습니다.

장점

일관성: 모든 리소스는 고유한 URI를 가지며, HTTP 메소드를 사용하기 때문에 일관된 인터페이스를 제공합니다.
확장성: 클라이언트와 서버가 서로 분리되어기 때문에 독립적으로 발전시킬 수 있습니다.
캐시 사용 가능: GET 요청 등에 캐시를 사용하여 성능을 향상시킬 수 있습니다.

단점

HTTP를 이용한 제약: RESTful API는 HTTP 프로토콜을 사용하므로 회선을 연속적으로 사용할 수 없고, 연결성을 보장하기 어렵습니다.
바이너리 데이터 처리: 바이너리 데이터를 전송하기 어렵거나, 텍스트 기반의 데이터 표현은 비효율적인 경우가 있습니다.

디자인

효과적인 RESTful API를 설계하기 위해서는 몇 가지 가이드라인을 따릅니다.

명사형 URI 사용: 리소스를 표현할 때는 동사보다는 명사를 사용하며 복수형으로 이름을 정의하는 것이 좋습니다. 예를 들어, “/orders/1” 이 “/getOrder/1” 보다 적합합니다.
표준 HTTP 메소드 사용: 기능에 대한 액션은 표준 HTTP 메소드를 사용하여 표현해야 합니다.
코드화 : 클라이언트는 오류가 발생했을 때, 상태 코드와 함께 오류 원인을 확인할 수 있는 메시지를 반환해야 합니다.
버전 관리 : API의 버전을 관리하여 클라이언트 호환성을 유지해야 합니다.

Java SpringBoot를 사용한 RESTful API 예제

이제 Java SpringBoot를 사용하여 간단한 RESTful API 예제를 보여드리겠습니다. 예제에서는 메모장 애플리케이션의 기본적인 CRUD 작업을 처리하는 API를 만들어보겠습니다.

프로젝트 구성 및 기본 설정

먼저, Java SpringBoot 프로젝트를 생성하고 필요한 의존성을 추가합니다. build.gradle 혹은 pom.xml 파일에 다음과 같이 작성합니다.

// build.gradle
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'
}

// pom.xml
<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
  </dependency>
  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
  </dependency>
</dependencies>

도메인 클래스 생성

메모장 애플리케이션의 도메인 클래스를 생성해줍니다. Memo.java 파일을 다음과 같이 작성합니다.

// Memo.java
@Entity
public class Memo {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String title;
    private String content;
    // 생성자, getter, setter, toString 생략
}

Repository 인터페이스 생성

메모장 애플리케이션의 레파지토리 인터페이스를 생성해줍니다. MemoRepository.java 파일을 다음과 같이 작성합니다.

// MemoRepository.java
public interface MemoRepository extends JpaRepository<Memo, Long> {
}

Controller 클래스 생성

메모장 애플리케이션의 컨트롤러 클래스를 생성해줍니다. MemoController.java 파일을 다음과 같이 작성합니다.

// MemoController.java
@RestController
@RequestMapping("/memos")
public class MemoController {
    @Autowired
    private MemoRepository memoRepository;

    @GetMapping("/")
    public List<Memo> getAllMemos() {
        return memoRepository.findAll();
    }

    @GetMapping("/{id}")
    public ResponseEntity<Memo> getMemoById(@PathVariable(value = "id") Long memoId) {
        Memo memo = memoRepository.findById(memoId).orElseThrow(() -> new ResourceNotFoundException("메모가 없습니다. : " + memoId));
        return ResponseEntity.ok().body(memo);
    }

    @PostMapping("/")
    public Memo createMemo(@Valid @RequestBody Memo memo) {
        return memoRepository.save(memo);
    }

    @PutMapping("/{id}")
    public ResponseEntity<Memo> updateMemo(@PathVariable(value = "id") Long memoId, @Valid @RequestBody Memo memoDetails) {
        Memo memo = memoRepository.findById(memoId).orElseThrow(() -> new ResourceNotFoundException("메모가 없습니다. : " + memoId));
        memo.setTitle(memoDetails.getTitle());
        memo.setContent(memoDetails.getContent());
        final Memo updatedMemo = memoRepository.save(memo);
        return ResponseEntity.ok(updatedMemo);
    }

    @DeleteMapping("/{id}")
    public Map<String, Boolean> deleteMemo(@PathVariable(value = "id") Long memoId) {
        Memo memo = memoRepository.findById(memoId).orElseThrow(() -> new ResourceNotFoundException("메모가 없습니다. : " + memoId));
        memoRepository.delete(memo);
        Map<String, Boolean> response = new HashMap<>();
        response.put("삭제되었습니다.", Boolean.TRUE);
        return response;
    }
}

테스트 및 확인

이제 작성한 RESTful API를 실행하여 테스트를 진행합니다. 클라이언트 도구를 사용하여 생성, 조회, 수정, 삭제 기능이 정상적으로 동작하는지 확인합니다.

이렇게 Java SpringBoot를 활용하여 간단한 메모장 애플리케이션의 RESTful API를 구현해볼 수 있습니다.

앞으로의 프로젝트에서 이러한 원리와 예제를 참고하여 다양한 애플리케이션에 RESTful API를 적용해보세요. 각각의 구성요소, 장단점 및 디자인 가이드라인을 숙지하시면, 효율적인 RESTful API를 구축하는 데에 도움이 될 것 같습니다.

함께 보면 좋은 글 :