API 명세서

API 명세서

• 소프트웨어 개발에서 사용되는 문서로 API의 이름, 파라미터(매개변수), 인터페이스, 반환 값 등의 구문, 인증 및 인가방법(동작방식), 데이터 전달 형식 등 API를 정확하게 호출하고 그 결과를 명확히 해석하는데 필요한 정보들을 일관된 형식으로 기술한 문서.

• 과거에는 사람이 이해하기 좋은 문서 형식으로 주로 작성되었으나, 최근에는 시스템이 해석하기에도 용이한 XML, YAML 구문등을 사용한 API 명세서 형식이 대두됨.

◼︎ API 명세서 필요성

• API의 설계, 개발 및 문서화 과정에서 용이
• 서로 다른 클라우드 서비스 간의 API연동에서 필요함.

◼︎ API 명세서 구성

1. API개요 : API의 목적과 사용방법을 간략히 설명. 어떤 기능을 제공하며, 어떤 문제를 해결하는 데 도움을 줄 수 있는지에 대한 개요를 제공.

2. 엔드포인트 및 요청방법 : API에서 제공하는 엔드포인트(Endpoint)와 각 엔트포인트에 대한 요청방법(GET, POST, PUT, DELETE 등)을 설명. 각각의 엔트포인트는 어떤 동작을 수행하는지 설명하고, 필요한 매개변수와 요청형식 등을 명시.

3. 매개변수와 반환값 : 각각의 API 요청에 필요한 매개변수와 해당 요청이 반환하는 값의 형식과 구조를 설명. 매개변수의 타입, 제한 사랑, 기본값 등을 명시하고, 반환값의 형식과 예시를 제공.

4. 오류처리 : API 요청 중에 발생할 수 있는 오류상황과 오류처리에 대한 설명을 포함. 어떤 오류가 발생할 수 있는지, 각각의 오류에 대한 응답 형식과 처리방법을 설명.

5. 인증과 보안 : API에 접근하기 위한 인증 방법과 보안 관련 사항을 설명. API토큰, OAuth, HTTPS 등의 인증 및 보안 기능에 대한 정보를 제공.

   
   

❖ REST API 의 API 명세서

▶︎ REST API의 명세서 보는법

1. 엔드포인트 확인: API 명세서에서 제공하는 엔드포인트(URI)를 확인.
   엔드포인트는 API에서 제공하는 각각의 기능이나 자원을 나타내는 URL.

2. 요청 방법 확인: 각각의 엔드포인트에 대해 지원하는 요청 방법(GET, POST, PUT, DELETE 등)을 확인.
   이를 통해 해당 엔드포인트로 어떤 동작을 수행할 수 있는지 알 수 있음.

3. 매개변수 확인: API 요청에 필요한 매개변수와 해당 매개변수의 타입, 제한 사항 등을 확인.
   필요한 경우 매개변수를 제공해야 하는지, 기본값이 있는지 등을 파악.

4. 반환 값 확인: API 요청에 대한 반환 값의 형식과 구조를 확인.
   반환 값은 JSON, XML 등의 형식으로 제공되며, 어떤 정보를 포함하고 있는지 파악.

5. 오류 처리 확인: API 요청 중에 발생할 수 있는 오류 상황과 해당 오류에 대한 응답 형식을 확인.
   어떤 오류 코드가 반환되는지, 오류 메시지가 포함되는지 등을 파악.

✔︎ REST API 명세서 예시(사용자 정보를 가져오는 GET요청):


	GET /users/{id}                             // 엔드포인트를 /users/{id}로하여, 사용자의 고유 식별자를 매개변수로 받음

	요청 방법:
	GET

	매개변수:
	- id: 사용자의 고유 식별자 (정수)

	반환 값:                                     //요청에 대한 반환 값은 JSON 형식으로 사용자의 정보를 포함
	{             
		"id": 1,
    	"name": "John Doe",
    	"email": "john.doe@example.com
    	}

	오류 처리:
	- 404 Not Found: 주어진 id에 해당하는 사용자를 찾을 수 없음
	- 500 Internal Server Error: 서버 내부 오류 발생

❖ GraphQL 의 API 명세서

▶︎ GraphQL의 API 명세서 보는법

1. 스키마 확인: GraphQL API 명세서에서 제공하는 스키마를 확인.
   스키마는 GraphQL에서 지원하는 모든 타입과 해당 타입의 필드, 관계 등을 정의하는 구조.

2. 쿼리 예시 확인: API 명세서에서 제공하는 예시 쿼리를 확인하여 어떤 데이터를 요청할 수 있는지 알아보기.
   예시 쿼리는 원하는 데이터의 구조와 필드를 보여줌.

3. 변수와 매개변수 확인: GraphQL은 변수를 사용하여 동적인 쿼리를 작성할 수 있음.
   API 명세서에서 제공하는 변수와 해당 변수의 타입, 제한 사항 등을 확인.
   쿼리에 사용되는 매개변수도 확인하여 어떤 값을 전달해야 하는지 알아보기.

4. 반환 값 확인: API 요청에 대한 반환 값의 구조와 필드를 확인.
   반환 값은 요청한 데이터에 해당하는 필드와 해당 필드의 타입을 포함.

5. 오류 처리 확인: GraphQL API 요청 중에 발생할 수 있는 오류 상황과 해당 오류에 대한 응답 형식을 확인.
   어떤 오류 코드가 반환되는지, 오류 메시지가 포함되는지 등을 파악.

✔︎ GraphQL API 명세서 예시(사용자 정보와 상품 정보를 가져오는 쿼리를 다루는 명세서):


	type Query {                   //Query 타입에는 user와 products 필드가 정의되어 있으며, 각각 사용자 정보와 상품 정보를 반환
    	user(id: ID!): User
        products(category: String!): [Product]
    }
    
    반환값 :
    type User {
     	id: ID!
        name: String
        email: String
        orders: [Order]
    }
    
    type Product {
    	id: ID!
        name: String
        price: Float
        category: String
    }
            
    type Order {
    	id: ID!
        date: String
        total: Float
        items: [Product]
    }