문서타입 - API 레퍼런스

ChatGPT로 효율적 영어쓰기

Nov 28. 2024

API 레퍼런스는 소프트웨어 개발 시 참고되는 문서입니다. "API"의 A는 Application, P는 Programming, I는 Interface로, 애플리케이션 프로그래밍에서 사용하는 인터페이스를 의미합니다. 또한 "레퍼런스"는 사전과 같은 참고용 자료를 뜻합니다. 참고 자료이기 때문에 처음부터 끝까지 통독하기보다는, 독자가 필요한 때 필요한 부분만 읽습니다.

자사에서 제공하는 라이브러리나 웹 API 등을 개발자가 사용할 경우, API 레퍼런스는 필수적입니다. 정보를 충분히 이해하기 쉽고 제공되지 않으면, 원활하게 개발을 진행할 수 없습니다.

⑴ 예제

API 레퍼런스 예제에서는 두 종류의 API 레퍼런스를 살펴봅니다. 첫 번째는, 메서드와 함수의 설명이 중심인 API 레퍼런스입니다. 프레젠테이션용 애플리케이션의 페이지를 조작하는 API를 예시로 제공합니다. 두 번째는, REST 스타일의 웹 API 레퍼런스입니다. HTTP 리퀘스트와 HTTP 리스폰스의 설명이 중심입니다. 도서 관리 애플리케이션에 서적을 추가하는 API를 예시로 제공합니다.

① 메소드/함수의 설명이 중심인 API 레퍼런스

예제1

* 참고번역

클래스 PresentationPage

텍스트, 이미지, 표 등 요소를 포함하는 프레젠테이션 페이지.

개요

메서드 | 반환값의 타입 | 설명

addTable(rows, columns) | Table | 페이지에 1개의 표를 추가

getTables() | Table[] | 페이지에 추가된 표의 리스트를 반환

<생략>

메서드

addTable(rows, columns)

페이지에 1개의 표를 추가.

표는 지정된 행 수와 열 수로, 페이지 왼쪽 상단에 추가됨.

파라미터

이름 | 타입 | 설명

rows | Integer | 표의 행 수

columns | Integer | 표의 열 수

반환값

Table - 추가된 표.

getTables()

페이지에 추가된 표의 리스트를 반환.

반환값

Table[] - 표 객체의 리스트.

<생략>

② REST 스타일의 웹API 레퍼런스

예제2

참고 번역

엔드포인트

책 책 생성 [POST] 책 조회 [GET] 책 업데이트 [PATCH] 책 삭제 [DELETE]

<생략>

책 생성

[POST] https://books-api.example.com/v1/bookshelves/{bookshelfId}/books

지정된 책장 내에 새로운 책 항목을 생성합니다.

리퀘스트

경로 파라미터

파라미터명 | 타입 | 설명

bookshelfId | string | 책장 식별자

쿼리 파라미터

없음.

리퀘스트 바디

프로퍼티명 | 타입 | 설명

title | string | 책 제목

author | string | 책저자명 선택사항

<생략>

예시

{

"title": "Moby Dick"

"author": "Herman Melville",

<생략>

응답

[200] - application/json

추가된 책 식별자를 리턴합니다.

예시

{

"bookID": "a000001234"

}

[400] - application/json

입력이 유효하지 않는 경우 오류를 리턴합니다.

⑵ 문서의 주요 요소와 구성: 메소드 / 함수

다음으로, 일반적인 API 레퍼런스의 주요 요소와 구성을 확인합니다. 우선, 메소드/함수 설명이 중심이 되는 API 레퍼런스입니다. 다양한 프로그래밍 언어의 라이브러리나 프레임워크가 대표적인 이용 사례입니다. 예제 (1)을 사용하여 설명합니다.

① 제목 (1)

페이지 또는 섹션의 제목입니다. 일반적으로 클래스가 있을 경우 클래스 단위로 페이지를 작성합니다.

② 전체 설명 (2)

해당 페이지 또는 섹션에 포함된 전체적인 내용을 1~몇 문장 정도로 간략히 설명합니다. 클래스의 섹션인 경우에는 그 설명입니다.

③ 요약 (3)

API 레퍼런스는 필요한 때에 참조하는 문서입니다. 따라서, 전체적인 이미지가 쉽게 이해될 수 있는 요약을 기재합니다. 독자는 우선 요약에서 전체를 파악하고, 거기서부터 자신이 원하는 세부 정보 (예를 들어 링크)를 탐색합니다. 즉, "요약 → 세부"의 형태로 구성됩니다.

예제(1)에서는 (3)의 "Summary"가 요약에 해당하며, 메소드의 목록이 기재되어 있습니다. 예제 내에서는 메소드만 있지만, 변수, 생성자, 프로퍼티 등의 정보가 있다면 그 요약도 기재할 수 있습니다.

④ 세부 사항

요약의 각 항목에 대한 상세 정보입니다. 여기서는 메소드나 함수의 세부 사항을 예로 듭니다. 예제를 보면, (4) "Methods" 이후에 각 메소드의 세부 사항이 하나씩 소개되어 있습니다. 앞서 설명한 것처럼, 상수나 생성자 등이 있으면 여기서 자세히 설명합니다.

이름 (5)

메소드나 함수의 이름입니다.

설명 (6)

메소드나 함수의 설명입니다. 후술하듯이, 동사로 시작하는 형태가 일반적입니다.

파라미터 (7)

메소드나 함수에 입력하는 정보입니다. 일반적으로, 메소드명이나 함수명에 포함된 각 파라미터 (parameter)를 표 형식으로 정리합니다. 예를 들어, 예제의 "addTable(rows, columns)"이라는 메소드가 있다면, "rows"와 "columns"의 설명이 포함됩니다.

반환값 (9이후)

메소드와 함수가 반환하는 정보입니다. Return이나 Returns와 같은 헤드라인으로 작성합니다.

⑤ 주요 요소와 구조

주요 요소를 요약하면 다음과 같습니다. "세부 사항"은 메소드나 함수에서 필수이지만, 상수나 생성자 등에서는 선택 사항입니다.

헤드라인

전체 설명

요약

세부 사항 (메소드/함수) 이름 설명 파라미터 반환값

세부 사항 (상수, 생성자 등) (선택 사항) 이름이나 설명 등

구조를 도식화하면, 아래 그림과 같습니다.

API 레퍼런스 (메소드/함수) 구조

⑶ 문서의 주요요소와 구조 - 웹 API

이어서, REST 스타일의 웹 API 레퍼런스입니다. 예제(2)을 사용하여 설명합니다.

① 목차 (11)

실행 가능한 처리와 작업의 목록입니다. 예제에서는 "Endpoints:"라는 제목으로 되어 있습니다. 페이지 내부가 아닌, 왼쪽이나 오른쪽의 목차 형태로 게시하는 것이 일반적입니다. API 레퍼런스는 참고용 자료이므로, 목차에서 전체 그림을 제시하면 독자가 필요한 정보를 더 쉽게 찾을 수 있습니다.

② 헤드라인 (12)

웹 API에서는 처리 내용(예제의 "Create a book")이나 HTTP 메서드(POST 및 GET 등)가 함께 헤드라인이 됩니다. 또한, 바로 옆에 엔드포인트(URL)도 게시됩니다.

③ 설명 (13)

처리의 전체적인 설명을 간결하게 기재합니다.

④ 요청 (14 이후)

웹 API에 입력하는 정보입니다. 일반적으로 "파라미터"와 "요청 본문"으로 나누어 게시합니다. 참고로 파라미터에는 경로(path)나 쿼리(query)가 있습니다. 요청의 예제도 게시하면 독자의 이해가 더 쉬워질 것입니다.

⑤ 응답 (16 이후)

웹 API가 반환하는 정보입니다. 각 응답에는 성공일 경우 "2xx", 실패일 경우 "4xx"와 같은 적절한 HTTP 상태 코드를 헤드라인에 부여합니다. 또한, 반환되는 정보를 이해하기 쉽게 하기 위해 가능한 한 예제도 게시합니다.

⑥ 주요 요소와 구조

주요 요소를 정리하면 다음과 같습니다. 목차는 페이지 내부에 배치되지 않는 경우가 많으므로, 여기서는 선택적 항목으로 둡니다.

목차 (선택적)

헤드라인

설명

요청

응답

구조를 도식화하면, 아래 그림과 같습니다.

API 참조 (웹API)의 구조

⑷ 표현의 포인트

위와 같이, API 레퍼런스라고 해도, API의 종류에 따라 구조가 달라질 수 있습니다. 하지만, 영어 표현의 측면에서 보면, 거의 대부분 공통적입니다.

① 주어를 생략하고 동사로 시작해서 작성하기

메서드나 함수, 혹은 웹 API의 처리를 설명하는 문장은, 주어를 생략하고 동사로 시작해서 작성합니다. 예제의 예문을 들면 다음과 같습니다.

⑥ Adds a table on the page.

⑩ Returns the list of tables added on the page.

⑬ Creates a new book item in the specified bookshelf.

(17) Returns the identifier of the added book.

이 예문들에서는 주어가 생략되고, 3인칭 단수 현재형 동사(예: Adds, Returns, Creates)로 문장이 시작됩니다. 생략은 완전한 문장으로 반드시 필요한 것이 아니거나, 의미에 문제가 없을 경우 흔히 일어나는 현상입니다. 독자는 문맥을 통해 주어를 추측할 수 있습니다. 예를 들어, ⑥에서는 "This method"와 같은 주어, ⑬에서는 "This API"와 같은 주어가 생략되어 있는 것으로 생각할 수 있습니다. 주어를 생략하고 동사를 앞에 두면, 독자는 "이것이 어떤 동작을 하는가"를 바로 파악할 수 있습니다. 특히 API 레퍼런스와 같은 참조 자료에서는, 목적의 정보를 찾기 쉽게 하는 것이 중요합니다.

또한, 예제에서는 모두 3인칭 단수 현재형(예: Adds)로 되어 있었습니다. 그러나, 조직이나 프로젝트에 따라 원형(예: Add)을 사용하는 경우도 있습니다. 생략하고 동사로 시작할 경우, 방침을 정하여 어느 쪽이든 통일하도록 합시다.

② 설명은 명사구도 가능

명사구란, 여러 단어가 모여 명사처럼 기능하는 표현입니다. 파라미터나 반환값 등에 대한 설명에서는, 주어와 동사가 포함된 완전한 문장이 아니라, 명사구만으로 작성되는 경우가 자주 있습니다. 문장은 아니지만, 문장의 끝에는 마침표가 놓이기도 합니다. 예제에서 확인해봅시다.

② A presentation page that contains elements such as texts, images, or tables.

⑧ The number of rows in the table.

⑮ The name of the book author. Optional.

참고로, ②의 동사 contains는 관계대명사 that에 연결된 동사로, 전체로서 문장이 아닙니다. 또한, ⑮에서는 "Optional"이라는 형용사도 사용되고 있습니다.

이와 같이 완전한 문장이 아닌, 명사구(경우에 따라서는 ⑮와 같은 형용사 포함)만으로 작성함으로써, 설명이 간결해집니다. 몇 차례 언급한 것처럼, 참조용 자료인 API 레퍼런스의 경우, 독자에게 중요한 것은 정보를 쉽게 찾을 수 있는지입니다. 따라서, 주어를 생략하고 동사로 시작하거나, 설명에 명사구를 사용하는 방식을 택합니다. API 레퍼런스를 영어로 작성할 때는 이 특징을 염두에 두고 작성하는 것이 좋습니다.

⑸ 중요한 단어와 표현집

다음으로 API 레퍼런스에서 자주 사용되는 단어와 표현을 확인합니다.

① 문두의 동사

메소드나 함수, 웹 API의 처리를 설명할 때는, 주어를 생략하고 동사로 시작하는 것이 일반적입니다. 이때 자주 사용되는 동사를 소개합니다. 예시에서 동사는 3인칭 단수 현재형(예: Adds 등)으로 되어 있지만, 원형(Add 등)으로 통일하는 방침을 세워도 무방합니다.

② Return의 표현

문장 앞에서 사용되는 동사 중 실제로 사용될 기회가 가장 많은 것은 "return"일 것입니다. 함수나 메소드, 또는 웹 API에서 반환되는 정보에 대해 설명합니다. 앞서 언급한 '문장 앞의 동사'에서 언급한 예문을 다시 봅시다.

예: Returns the size of this file in bytes.

(이 파일의 사이즈를 바이트 단위로 반환합니다.)

예문에서 Returns의 목적어, 즉 반환되는 정보는 "the size"입니다. 이 목적어의 위치에는 다양한 단어가 들어갑니다. 몇 가지 예를 들어 봅시다.

☞ 불리언 값 (true, false)

예: Returns true if the given key exists, false otherwise.

(주어진 키가 존재하는 경우 true를 반환합니다. 그렇지 않으면 false를 반환합니다.)

조건에 맞으면 true (또는 false), 그렇지 않으면 반대 값을 반환하는 경우가 있습니다. "그렇지 않으면 false"는 위 예와 같이 문장 끝에 콤마로 구분하여, "false otherwise" 또는 ", else false"로 표현할 수 있습니다. 반대로 "그렇지 않으면 true"는 ", true otherwise."나 ", else true."로 합니다.

또한, 인수로 주어진 정보에 대해서는 예와 같이 given을 사용하여 "given key"라고 하거나, specified를 사용하여 "specified value"(지정된 값)라고 표현하기도 합니다.

☞ 배열, 리스트 (array, list)

예: Returns a paginated list of registered users.

(등록된 유저의 페이지네이션된 리스트를 반환합니다.)

☞ 값 (value)

예: Returns the current value as a string.

(현재의 값을 문자열로 반환합니다.)

☞ 수 (number)

예: Returns the number of rows in this table.

(이 표의 행 수를 반환합니다.)

예문에 있는 'the number of ○○'는 '○○의 수'입니다. 'a number of ○○'는 '다수의 ○○'입니다. the와 a에 따라 의미가 달라지므로 주의합시다.

☞ 사이즈, 길이, 폭 등 (size, length, width 등)

예: Returns the length of the given string.

(주어진 문자열의 길이를 반환합니다.)

③ 헤드라인 단어

API 레퍼런스는 참조용 자료이므로, 독자가 원하는 정보를 찾기 쉽게 합니다. 그러므로 일반적으로 자주 사용되는 표제어를 사용합시다. 예를 들어, 페이지 내 섹션 표제어나 표의 헤더가 해당합니다. 그런 표제어에 사용할 수 있는 단어들을 정리합니다. 아래에 사용 용도를 상정해 구분해 두었지만, 적절하다면 다른 용도로도 사용할 수 있습니다.