<stdio.han>

Rest API는 API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처이다.

좀더 간단하게 말하자면 서버의 api가 적절하게 http를 준수하며 잘 설계되었다면 RESTful하게 설계되어 있다고 생각하면 된다.

고유 리소스 식별자

서버는 고유한 리소스 식별자로 각 리소스를 식별한다. REST 서비스의 경우 서버는 일반적으로 URL을 사용하여 리소스 식별을 수행한다. URL은 리소스에 대한 경로를 지정한다. URL은 웹페이지를 방문하기 위해 브라우저에 입력하는 웹 사이트 주소와 유사하다. URL은 요청 엔드포인트라고도 하며 클라이언트가 요구하는 사항을 서버에 명확하게 지정한다.

메서드

HTTP 베서드는 리소스에 수행해야 하는 작업을 서버에 알려준다.

GET

클라이언트는 GET을 사용하여 서버의 지정된 URL에 있는 리소스에 엑세스한다. GET 요청을 캐싱하고 RESTful API 요청에 파라미터를 넣어 전송하여 전송 전에 데이터를 필터링하도록 서버에 지시할 수 있다.

POST

클라이언트는 POST를 사용하여 서버에 데이터를 전송한다. 여기에는 요청과 함께 데이터 표현이 포함된다. 동일한 POST 요청을 여러 번 전송하면 동일한 리소스를 여러 번 생성하는 부작용이 있다.

PUT

클라이언트는 PUT을 사용하여 서버의 기존 리소스를 업데이트한다. POST와 달리 RESTful 웹 서비스에서 동일한 PUT요청을 여러 번 전송해도 결과는 동일하다.

예를들어 API의 리소스 식별자를 중복 없이 고유하게 잘 만들고 해당 API에 적절하게 HTTP 메서드를 사용했다면 RESTful 하게 설계했다고 볼 수 있다.

API를 쓸모 있게 하려면 잘 작성된 문서도 곁들여야 한다. API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.

• 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.

• 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.

/**
 * 제네릭 스택 클래스.
 *
 * @param <E> 스택에 저장할 요소의 타입
 */
public class GenericStack<E> {
    private List<E> elements = new ArrayList<>();

    /**
     * 스택에 요소를 추가합니다.
     *
     * @param element 추가할 요소
     */
    public void push(E element) {
        elements.add(element);
    }

    /**
     * 스택에서 요소를 제거하고 반환합니다.
     *
     * @return 제거된 요소
     * @throws EmptyStackException 스택이 비어 있는 경우
     */
    public E pop() {
        if (elements.isEmpty()) {
            throw new EmptyStackException();
        }
        return elements.remove(elements.size() - 1);
    }
}

• 열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.

• 애너테이션 타입을 문서화할 때는 멤버들에도 모든 주석을 달아야 한다.

• 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.

핵심 정리 : 문서화 주석은 여러분 API를 문서화하는 가장 훌륭하고 효과적인 방법이다. 공개 API라면 빠짐없이 설명을 달아야 한다. 표준 규약을 일관되게 지키자. 문서화 주석에 임의의 HTML태그를 사용할 수 있음을 기억하라. 단, HTML 메타문자는 특별하게 취급해야 한다.