Rest API

Rest API 공통 가이드는 자율주행모빌리티 운영 플랫폼에서 제공하는 API를 사용해 애플리케이션을 개발할 때 미리 알아두어야 하는 내용을 설명합니다.

💡 사전 준비 사항

내 서비스 확인

플랫폼에서 제공하는 API를 사용하기 위해서는 해당 API에 대한 권한이 필요합니다. API 별 권한은 사용자 서비스의 개발자 센터 > 내 서비스에서 확인하실 수 있습니다.

💡 접근 토큰 발급

기본적으로 자율주행모빌리티 운영 플랫폼에서 제공하는 API는 OAuth 2.0 Bearer 인증 방식을 사용합니다.

API 인증은 사용자 서비스 계정(ID, Password)을 이용해 접근 토큰(access token)을 획득하여 사용하실 수 있습니다. API를 호출할 때 인증 API를 통해 받은 접근 토큰의 값을 전송해야 합니다.

1. API 기본 정보

Method	요청 URL	설명
POST	https://service.mqnicrnd5.com/auth	접근 토큰 발급

2. 요청 파라미터

요청 파라미터 명	타입	필수여부	기본값	설명
userName	string	Y	-	사용자 서비스 로그인 시 사용하는 아이디 입력
password	string	Y	-	사용자 서비스 로그인 시 사용하는 패스워드 입력

3. 응답 파라미터

응답 파라미터 명	타입	설명
access_token	string	접근 토큰, 발급 후 expires_in 파라미터에 설정된 시간(초)이 지나면 만료됨
expires_in	string	접근 토큰의 유효 기간(초 단위)

4. 요청 예시

Curl

curl --location 'https://service.mqnicrnd5.com/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "userName": "<사용자 서비스 ID>",
    "password": "<사용자 서비스 Password>"
}'

Java

import com.google.gson.Gson;
import com.google.gson.JsonObject;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.util.HashMap;
import java.util.Map;
import java.net.URL;

public class CallAPI {

    public static void main(String[] args) {
        String userName = "<사용자 서비스 ID>"; // Change it
        String password = "<사용자 서비스 Password>"; //Change it

        JsonObject jsonObject = new JsonObject();
        jsonObject.addProperty("userName", userName);
        jsonObject.addProperty("password", password);

        String apiURL = "https://service.mqnicrnd5.com/auth";

        Map<String, String> requestHeaders = new HashMap<>();
        requestHeaders.put("Content-Type", "application/json; utf-8");

        String responseBody = post(apiURL, jsonObject, requestHeaders);
        System.out.println(responseBody);
    }

    private static String post(String apiUrl, JsonObject requestBody, Map<String, String> requestHeaders) {
        HttpURLConnection con = connect(apiUrl);
        try {
            con.setRequestMethod("POST");
            con.setDoOutput(true);
            for (Map.Entry<String, String> header : requestHeaders.entrySet()) {
                con.setRequestProperty(header.getKey(), header.getValue());
            }
            
            Gson gson = new Gson();
            String jsonRequestBody = gson.toJson(requestBody);

            try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
                byte[] postData = jsonRequestBody.getBytes();
                wr.write(postData);
            }

            int responseCode = con.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) { // 정상 호출
                return readBody(con.getInputStream());
            } else { // 오류 발생
                return readBody(con.getErrorStream());
            }
        } catch (IOException e) {
            throw new RuntimeException(e);
        } finally {
            con.disconnect();
        }
    }


    private static HttpURLConnection connect(String apiUrl) {
        try {
            URL url = new URL(apiUrl);
            return (HttpURLConnection) url.openConnection();
        } catch (MalformedURLException e) {
            throw new RuntimeException("API URL이 잘못되었습니다. : " + apiUrl, e);
        } catch (IOException e) {
            throw new RuntimeException("연결이 실패했습니다. : " + apiUrl, e);
        }
    }


    private static String readBody(InputStream body) {
        InputStreamReader streamReader = new InputStreamReader(body);


        try (BufferedReader lineReader = new BufferedReader(streamReader)) {
            StringBuilder responseBody = new StringBuilder();


            String line;
            while ((line = lineReader.readLine()) != null) {
                responseBody.append(line);
            }


            return responseBody.toString();
        } catch (IOException e) {
            throw new RuntimeException("API 응답을 읽는 데 실패했습니다.", e);
        }
    }

}

Python

import requests
import json

def send_post_request():
    url = "https://service.mqnicrnd5.com/auth"
    
    # Create your data object
    data_object = {
        "userName": "<사용자 서비스 ID>", # Change it
        "password": "<사용자 서비스 Password>" # Change it
    }  # Customize this with your data object
    
    # Convert data object to JSON
    json_data = json.dumps(data_object)
    
    # Set headers
    headers = {
        "Content-Type": "application/json"
    }
    
    # Send POST request
    response = requests.post(url, data=json_data, headers=headers)
    
    # Print response
    print("Response Code:", response.status_code)
    print("Response:", response.text)

if __name__ == "__main__":
    send_post_request()
    

5. 응답 예시

{
    "access_token": "eyJadAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrAAAQosjWDJieBiQZc3to9YQp6HDLvrmyKC+6+iZ3gq7qrkqf50ljZC+LgoqrjflTpQ2bH_KErhh_AcuuqhcbCkiJAGaaRZra4fx2cCTW7dYQwTrj2KPw2IdbNLfBq-t3Sl29QNC1VSYoBf_w",
    "expires_in": 21600
}

💡 API 호출

발급받은 접근 토큰을 인증 헤더(Authorization) 에 넣어 호출하시면 됩니다. 중요한 것은, 발급받은 토큰 앞에 "Bearer " 라는 문자열을 붙여아 합니다.

Authorization: Bearer <token>

💡 오류 코드

주요 오류 코드

HTTP 코드	에러 코드	에러 메세지	조치 방안
400	C004	Invalid Input Value	API의 인터페이스에 맞게 파라미터를 입력하였는지 확인해보시길 바랍니다.
401	C004	Access Denied (권한이 존재하지 않습니다.)	해당 API의 권한이 존재하지 않습니다. 사용자 서비스를 통해 신청 후 이용해주세요.
401	C004	Authentication Failed (인증에 실패하였습니다.)	토큰 값이 들어가지 않거나 만료된 경우입니다.
403	C004	Access Denied	사용자 서비스에 등록되지 않은 계정입니다. 계정 등록 후 이용해주세요.
404	C004	Page Not Found (API가 존재하지 않습니다.)	호출한 URL이 존재하지 않습니다.
500	C005	Server Error	서버 내부 에러가 발생하였습니다. 사용자 서비스의 Q&A에 올려주시면 신속히 조치하겠습니다.

오류 메세지 형식

응답 파라미터 명	타입	설명
message	string	오류 메세지입니다.
status	integer	오류 상태코드입니다.
code	string	오류 코드입니다.