Dataspace API specification (v2)
Download OpenAPI specification:Download
(출시일: 2024-05-30)
Dataspace 에서 제공하는 API 에 대해 명세합니다.
- 데이터스페이스 API 는 HTTP Basic 인증방식을 사용합니다.
- HTTPS 통신과 TLS 버전 1.2 이상만 지원합니다.
Space ID, API 인증키가 필수값으로 요구됩니다.
Space ID : ‘데이터스페이스’당 1개의 Space ID가 자동으로 발급되어, 별도의 발급 절차가 필요하지 않습니다. 데이터스페이스에 소속된 사용자라면 누구나 조회할 수 있습니다.
API 인증키 : 발급 이후 조회할 수 있으며, 발급 및 재발급 권한은 ‘데이터스페이스 관리자 계정’에게 있습니다.
데이터스페이스에 로그인 후, [API] > [API 키] 메뉴에 접근하여 조회 및 복사하실 수 있습니다.
로그인 후에도 [API 키] 메뉴에 접근할 수 없다면, '데이터스페이스’에 멤버로 등록되었는지 확인해보세요.
데이터스페이스의 모든 API는 HTTP Authorization header 에 Basic <crendentials>을 추가해서 요청하도록 설계되어 있습니다.
Space ID 와 API 인증키 사이에 : (콜론)을 추가하고 base64(No Padding)로 인코딩하세요.
credentials = base64({Space ID}:{API 인증키})
인코딩된 값을 API 의 Authorization header 를 다음과 같이 설정하세요.
Authorization: Basic base64({Space ID}:{API 인증키})
아래와 같은 형태로 API 요청이 가능합니다.
GET /v2/responses/... HTTP/1.1
Authorization: Basic
설문 목록 조회
설문 목록을 조회합니다. 설문에 속한 수집그룹들의 상태에 따른 필터링이 가능합니다.
필터를 지정하지 않으면 모든 설문을 조회하고, RUNNING은 현재 진행중인 수집그룹이 있는 설문만 조회합니다.
설문 ID 와 설문 제목, 그리고 생성일자 및 최종 수정일자를 조회할 수 있습니다. 생성일 역순으로 1000 건씩 조회합니다.
Authorizations:
query Parameters
| collectGroupsStatus | string Value: "RUNNING" |
| nextSurveyId | string Example: nextSurveyId=a01h1mzpact2df4gjfgq865f1gx response 에서 받은 nextSurveyId 값을 넣어서 다음 페이지의 설문 1000건을 조회할 수 있습니다. |
Responses
Response samples
- 200
- 400
- 500
{- "surveys": [
- {
- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "title": "생활 관련 조사",
- "createdAt": "2023-10-02T00:00:00",
- "updatedAt": "2023-10-02T00:00:00"
}
], - "nextSurveyId": "a01h1mzpact2df4gjfgq865f1gx"
}설문 정보 조회
설문 ID(surveyId) 를 통해 설문 정보를 조회합니다.
Authorizations:
path Parameters
| surveyId required | string Example: a01hb7vt01vpahrwjyxgd28sf3a |
Responses
Response samples
- 200
- 400
- 500
{- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "title": "생활 관련 조사",
- "questions": [
- {
- "rank": 1,
- "type": "SingleChoice",
- "text": "<p>거주하시는 집의 형태는 다음 중 어디에 해당하나요?</p>",
- "options": [
- {
- "rank": 1,
- "text": "<p>1번 보기</p>"
}
]
}
], - "parameters": [
- {
- "parameterKey": "region",
- "isCollectable": true
}
], - "createdAt": "2023-10-02T00:00:00",
- "updatedAt": "2023-10-02T00:00:00"
}수집그룹 목록 조회
설문 내 모든 수집그룹들의 정보를 생성일자 순으로 조회합니다.
Authorizations:
path Parameters
| surveyId required | string Example: a01hb7vt01vpahrwjyxgd28sf3a |
Responses
Response samples
- 200
- 400
- 500
[- {
- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "name": "기본 링크 수집그룹",
- "channel": "PUBLIC_LINK",
- "state": "READY",
- "targetCnt": 100,
- "startedAt": "2023-10-04T00:00:00",
- "completedAt": "2023-10-10T00:00:00",
- "isUsingHmac": false,
- "createdAt": "2023-10-02T00:00:00",
- "updatedAt": "2023-10-03T00:00:00"
}
]수집그룹 정보 조회
수집그룹 ID(collectGroupId) 를 통해 수집그룹 정보를 조회합니다.
Authorizations:
path Parameters
| collectGroupId required | string |
Responses
Response samples
- 200
- 400
- 500
{- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "name": "기본 링크 수집그룹",
- "channel": "PUBLIC_LINK",
- "state": "READY",
- "targetCnt": 100,
- "startedAt": "2023-10-04T00:00:00",
- "completedAt": "2023-10-10T00:00:00",
- "isUsingHmac": false,
- "createdAt": "2023-10-02T00:00:00",
- "updatedAt": "2023-10-03T00:00:00"
}응답 URL 조회
수집그룹에 대한 응답 URL 목록을 조회합니다.
기본 링크(PUBLIC_LINK) 수집그룹의 경우에만 적용 가능합니다.
파라미터 값이 적용된 응답 URL 목록을 반환합니다.
Authorizations:
path Parameters
| collectGroupId required | string |
Request Body schema: application/json
| parameters | Array of objects 생성할 응답 URL 들에서 사용할 파라미터 값들. URL 별로 파라미터 Key 에 해당하는 파라미터 값들을 지정할 수 있습니다. |
Responses
Request samples
- Payload
[- {
- "parameters": {
- "age": 30,
- "name": "김패널",
- "uid": "47d5c15a"
}
}, - {
- "parameters": {
- "age": 22,
- "name": "홍길동",
- "uid": "3a5eq19s"
}
}, - {
- "parameters": {
- "age": 44,
- "name": "이오픈",
- "uid": "ba1r6s2g"
}
}
]Response samples
- 200
- 400
- 500
[
]응답 조회
설문 ID 를 받고, 해당 설문에 대한 응답을 조회합니다. pageToken 기준으로 1000건의 응답씩 응답 역순으로 조회할 수 있습니다.
Authorizations:
query Parameters
| surveyId required | string Example: surveyId=a01hb7vt01vpahrwjyxgd28sf3a |
| startDateTime | string <date-time> Example: startDateTime=2020-01-01T00:00:00 응답 제출시각 기준으로 조회할 때 범위 시작 시각입니다. (해당 시각 미포함) 값이 없으면 가장 오래된 응답부터 조회합니다. |
| endDateTime | string <date-time> Example: endDateTime=2020-01-02T00:00:00 응답 제출시각 기준으로 조회할 때 범위 종료 시각입니다. (해당 시각 포함) 값이 없으면 가장 최근 응답까지 조회합니다. |
| parameterField | string Enum: "ANSWERS" "PARAMETERS" Example: parameterField=ANSWERS 파라미터 값이 포함된 응답일 경우, 파라미터 키와 값을 어떤 필드에 포함할지 선택할 수 있습니다. |
| pageToken | string Example: pageToken=ZjJrdXJyeWo= response 에서 받은 pageToken 값을 넣어서 다음 페이지의 응답 1000건을 조회할 수 있습니다. |
Responses
Response samples
- 200
- 400
- 500
{- "surveyId": "a01hb7vt01vpahrwjyxgd28sf3a",
- "responses": [
- {
- "serial": "aLACT7Q8Key9C",
- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "startedAt": "2023-10-02T12:00:00",
- "finishedAt": "2023-10-02T12:10:00",
- "parameters": {
- "UID": "3a5eq19s",
- "storeId": 1213
}, - "answers": [
- {
- "name": "Q1",
- "rank": 1,
- "answer": [
- {
- "num": 6,
- "str": "주관식 답변입니다."
}
]
}
]
}
], - "pageToken": "ZjJrdXJyeWo="
}응답 메타데이터 조회
설문 ID 를 받고, 해당 설문에 대한 응답의 메타데이터를 조회합니다. pageToken 기준으로 1000건의 응답씩 응답 역순으로 조회할 수 있습니다.
Authorizations:
query Parameters
| surveyId required | string Example: surveyId=a01hb7vt01vpahrwjyxgd28sf3a |
| startDateTime | string <date-time> Example: startDateTime=2020-01-01T00:00:00 응답 제출시각 기준으로 조회할 때 범위 시작 시각입니다. (해당 시각 미포함) 값이 없으면 가장 오래된 응답부터 조회합니다. |
| endDateTime | string <date-time> Example: endDateTime=2020-01-02T00:00:00 응답 제출시각 기준으로 조회할 때 범위 종료 시각입니다. (해당 시각 포함) 값이 없으면 가장 최근 응답까지 조회합니다. |
| pageToken | string Example: pageToken=ZjJrdXJyeWo= response 에서 받은 pageToken 값을 넣어서 다음 페이지의 응답 메타데이터 1000건을 조회할 수 있습니다. |
Responses
Response samples
- 200
- 400
- 500
{- "answerSheets": [
- {
- "answerUid": "47d5c15",
- "serial": "aLACT7Q8Key9C",
- "collectGroupId": "a01h94kt4fyzmp64h40gzyvrjj7",
- "startedAt": "2023-10-02T12:00:00",
- "finishedAt": "2023-10-02T12:10:00"
}
], - "pageToken": "ZjJrdXJyeWo="
}