StarDots.io Logo

StarDots

문서 홈

Open API

이 장에서는 Open API 통합 방법을 소개합니다. 아래 지식은 개발자를 위한 것이며, 일정 수준의 프로그래밍 기초가 있다고 가정합니다.

AI 에이전트인가요? Markdown 문서 보기
이 페이지의 내용

인증

StarDots는 클라이언트에서 시작한 HTTP 요청의 헤더 필드를 읽고 관련 필드를 검증하여 인증을 수행합니다. 따라서 모든 Open API 요청은 이러한 인증 필드 정보를 포함해야 하며, 이러한 필드는 대소문자를 구분하고 모두 소문자여야 한다는 점을 유의하세요.

  • x-stardots-timestamp
    설명
    현재 타임스탬프(초 단위). StarDots 서버와의 차이는 60초를 초과할 수 없습니다. 참고: StarDots의 시간대는 Asia/Singapore, UTC+8입니다.
  • x-stardots-nonce
    설명
    4~20자의 임의 문자열로, 대문자, 소문자, 숫자만 포함할 수 있습니다. 이 값은 60초 내에 유일해야 합니다.
  • x-stardots-key
    설명
    StarDots에서 발급한 키 정보입니다.
  • x-stardots-sign
    설명
    서명 필드는 위의 필드를 특정 서명 알고리즘에 따라 결합하여 생성된 문자열입니다. 구체적인 서명 알고리즘은 다음에 소개됩니다.

서명 알고리즘

다음 필드 값을 가정합니다.

key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
secret
Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp
x-stardots-timestamp
1728958751
x-stardots-nonce
fQvDmMLnKE
x-stardots-key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
Key와 Secret은 StarDots에서 발급하며, 콘솔 설정 페이지에서 찾을 수 있습니다.

그런 다음 위의 필드 값을 조합합니다.

needSignStr = x-stardots-timestamp + "|" + secret + "|" + x-stardots-nonce

다음으로 위에서 조합한 문자열의 MD5 다이제스트를 계산합니다.

signStrAfterMD5 = md5("1728958751|Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp|fQvDmMLnKE")
signStrAfterMD5 = "51dabfe4b47e73d4a3b85fe29c4f1e82"

마지막으로 요약 문자열을 대문자로 변환합니다.

sign = signStrAfterMD5.toUpperCase()
sign = "51DABFE4B47E73D4A3B85FE29C4F1E82"

따라서 x-stardots-sign 필드의 최종 값은 다음과 같습니다. 51DABFE4B47E73D4A3B85FE29C4F1E82

공통 HTTP 응답 본문

모든 인터페이스 응답은 통합된 데이터 구조를 유지합니다.

  • code
    데이터 유형
    number
    필수
    예
    설명
    서비스 응답 코드. 200은 성공을 의미합니다.
  • message
    데이터 유형
    string
    필수
    예
    설명
    작업 결과의 메시지 안내.
  • requestId
    데이터 유형
    string
    필수
    예
    설명
    요청에 대한 고유 번호로, 문제 해결에 사용할 수 있습니다.
  • success
    데이터 유형
    boolean
    필수
    예
    설명
    비즈니스 작업이 성공했는지 여부를 나타냅니다.
  • ts
    데이터 유형
    number
    필수
    예
    설명
    서버 밀리초 타임스탬프.
  • data
    데이터 유형
    any
    필수
    예
    설명
    비즈니스 데이터 필드. 이 필드는 어떤 데이터 유형일 수 있습니다. 특정 데이터 유형에 대해서는 해당 인터페이스를 참조하십시오.

기능 인터페이스

모든 인터페이스에는 요청 속도 제한이 있으며, 모든 인터페이스는 동일한 속도 제한 규칙을 공유합니다. 현재 StarDots의 속도 제한은 분당 300회입니다.

요청 엔드포인트

https://api.stardots.io

공간 목록

공간 목록 데이터를 가져옵니다.

요청 방법
GET
요청 경로
/openapi/space/list
요청 콘텐츠 유형
application/json
응답 콘텐츠 유형
application/json

요청 매개변수

  • page
    데이터 유형
    number
    필수
    아니오
    설명
    페이지 번호, 기본 값은 1입니다.
  • pageSize
    데이터 유형
    number
    필수
    아니오
    설명
    페이지당 항목 수는 1에서 100까지이며, 기본 값은 20입니다.

요청 데모

/openapi/space/list?page=1&pageSize=50

응답 필드

  • name
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다.
  • public
    데이터 유형
    boolean
    필수
    예
    설명
    공간의 접근 가능성이 false인지 여부입니다.
  • createdAt
    데이터 유형
    number
    필수
    예
    설명
    공간이 생성된 시스템 타임스탬프(초 단위)입니다. 시간대는 UTC+8입니다.
  • fileCount
    데이터 유형
    number
    필수
    예
    설명
    이 공간에 있는 파일 수입니다.

응답 데모

{
    "code": 200,
    "data": [
        {
            "createdAt": 1723789637,
            "fileCount": 2,
            "name": "star",
            "public": true
        }
    ],
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

공간 생성

새로운 공간을 생성합니다.

요청 방법
PUT
요청 경로
/openapi/space/create
요청 콘텐츠 유형
application/json
응답 콘텐츠 유형
application/json

요청 매개변수

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.
  • public
    데이터 유형
    boolean
    필수
    아니오
    설명
    공간이 공개적으로 접근 가능한지 여부를 지정합니다. 기본 값은 false입니다.

요청 데모

{
    "public": false,
    "space": "stardots"
    }

응답 필드

필드 없음

응답 데모

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

공간 삭제

기존 공간을 삭제합니다. 이 공간에 파일이 없음을 확인해야 합니다. 그렇지 않으면 삭제가 실패합니다.

요청 방법
DELETE
요청 경로
/openapi/space/delete
요청 콘텐츠 유형
application/json
응답 콘텐츠 유형
application/json

요청 매개변수

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.

요청 데모

{
    "space": "stardots"
    }

응답 필드

필드 없음

응답 데모

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

공간 접근성

공간의 접근성을 전환합니다.

요청 방법
POST
요청 경로
/openapi/space/accessibility/toggle
요청 콘텐츠 유형
application/json
응답 콘텐츠 유형
application/json

요청 매개변수

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.
  • public
    데이터 유형
    boolean
    필수
    아니오
    설명
    공간이 공개적으로 접근 가능한지 여부를 지정합니다. 기본값은 false입니다.

요청 데모

{
    "public": false,
    "space": "stardots"
    }

응답 필드

필드 없음

응답 데모

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

공간 내 파일 목록

공간 내 파일 목록을 가져옵니다. 목록은 파일 업로드 시간을 기준으로 내림차순으로 정렬됩니다.

요청 방법
GET
요청 경로
/openapi/file/list
요청 콘텐츠 유형
application/json
응답 콘텐츠 유형
application/json

요청 매개변수

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.
  • page
    데이터 유형
    number
    필수
    아니오
    설명
    페이지 번호, 기본값은 1입니다.
  • pageSize
    데이터 유형
    number
    필수
    아니오
    설명
    페이지당 항목 수는 1에서 100 사이이며, 기본값은 20입니다.

요청 데모

{
    "space": "stardots",
    "page": 1,
    "pageSize": 20,
    }

응답 필드

  • page
    데이터 유형
    number
    필수
    예
    설명
    페이지 번호, 기본값은 1입니다.
  • pageSize
    데이터 유형
    number
    필수
    예
    설명
    페이지당 항목 수는 1에서 100 사이이며, 기본값은 20입니다.
  • totalCount
    데이터 유형
    number
    필수
    예
    설명
    항목의 총 개수입니다.
  • list
    데이터 유형
    array<object>
    필수
    예
    설명
    파일 목록 배열입니다.
  • list.name
    데이터 유형
    string
    필수
    예
    설명
    파일의 이름입니다.
  • list.byteSize
    데이터 유형
    number
    필수
    예
    설명
    파일 크기(바이트 단위)입니다.
  • list.size
    데이터 유형
    string
    필수
    예
    설명
    파일 크기, 가독성을 위한 형식입니다.
  • list.uploadedAt
    데이터 유형
    number
    필수
    예
    설명
    파일 업로드 타임스탬프(초 단위)입니다. 시간대는 UTC+8입니다.
  • list.url
    데이터 유형
    string
    필수
    예
    설명
    파일의 접근 주소입니다. 공간의 접근성이 비공개일 경우 이 필드 값은 접근 티켓을 포함하며, 이는 20초 동안 유효합니다.

응답 데모

{
    "code": 0,
    "data": {
        "list": [
            {
                "byteSize": 3600000,
                "name": "star",
                "size": "35KB",
                "uploadedAt": 1723789637,
                "url": "https://....."
            }
        ],
        "page": 1,
        "pageSize": 10,
        "totalCount": 1
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

파일 접근 티켓

파일에 대한 접근 티켓을 받습니다. 공간의 접근성이 비공개일 경우, 공간 내 파일에 접근하려면 접근 티켓을 가져야 하며, 그렇지 않으면 요청이 거부됩니다.

요청 방법
POST
요청 경로
/openapi/file/ticket
요청 콘텐츠 유형
application/json
응답 콘텐츠 유형
application/json

요청 매개변수

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.
  • filename
    데이터 유형
    string
    필수
    예
    설명
    파일의 이름입니다.

요청 데모

{
    "filename": "1.jpg",
    "space": "stardots"
    }

응답 필드

  • ticket
    데이터 유형
    string
    필수
    예
    설명
    접근 티켓입니다.

응답 데모

{
    "code": 200,
    "data": {
        "ticket": "a312.."
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

파일 업로드

파일을 공간에 업로드합니다. 이 요청은 양식 형태로 요청을 시작해야 합니다.

요청 방법
PUT
요청 경로
/openapi/file/upload
요청 콘텐츠 유형
multipart/form-data
응답 콘텐츠 유형
application/json

요청 매개변수

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.
  • file
    데이터 유형
    binary
    필수
    예
    설명
    파일의 바이너리 스트림입니다. 파일 이름은 170자를 넘을 수 없으며, 파일 크기는 10MB를 넘을 수 없습니다.

응답 필드

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.
  • filename
    데이터 유형
    string
    필수
    예
    설명
    파일의 이름입니다.
  • url
    데이터 유형
    string
    필수
    예
    설명
    파일의 접근 링크입니다. 공간의 접근성이 비공개일 경우, 접근 링크에는 접근 티켓이 포함됩니다.

응답 데모

{
    "code": 200,
    "data": {
        "filename": "1.png",
        "space": "space",
        "url": "https://i.stardots.io/space/1.png"
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

파일 삭제

공간 내의 파일을 삭제합니다. 이 인터페이스는 일괄 작업을 지원합니다.

요청 방법
DELETE
요청 경로
/openapi/file/delete
요청 콘텐츠 유형
application/json
응답 콘텐츠 유형
application/json

요청 매개변수

  • space
    데이터 유형
    string
    필수
    예
    설명
    공간의 이름입니다. 문자나 숫자의 조합만 가능하며, 길이는 4에서 15자입니다.
  • filenameList
    데이터 유형
    array<string>
    필수
    예
    설명
    파일 이름 배열입니다.

요청 데모

{
    "filenameList": ["1.jpg", "2.jpg"],
    "space": "stardots"
    }

응답 필드

필드 없음

응답 데모

{
    "code": 0,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
    }

서버 응답 코드

서버 응답 코드는 서버가 클라이언트에게 반환하는 응답 코드입니다. 서버가 요청을 처리한 결과를 나타냅니다.

  • 200
    설명
    성공
  • 504
    설명
    요청 시간 초과
  • 999999
    설명
    서버 내부 오류
  • 100000
    설명
    요청 매개변수 오류
  • 100001
    설명
    접근 티켓 만료
  • 100002
    설명
    인간 인증 실패
  • 100003
    설명
    인증 코드가 올바르지 않습니다.
  • 100004
    설명
    계정이 존재하지 않습니다.
  • 100005
    설명
    계정 비밀번호가 일치하지 않습니다.
  • 100006
    설명
    구독 계획이 존재하지 않습니다.
  • 100007
    설명
    문자/이메일 발송이 너무 자주 발생합니다.
  • 100008
    설명
    문자/이메일 발송 횟수가 제한을 초과했습니다.
  • 100009
    설명
    공간/저장소가 존재하지 않습니다.
  • 100010
    설명
    공간/저장소가 이미 존재합니다.
  • 100011
    설명
    공간/저장소가 비어있지 않습니다.
  • 100012
    설명
    작업이 너무 자주 발생합니다.
  • 100013
    설명
    공간/저장소 수량 할당량이 초과되었습니다.
  • 100014
    설명
    파일 수량 할당량이 초과되었습니다.
  • 100015
    설명
    트래픽 전송 할당량이 소진되었습니다.
  • 100016
    설명
    구독 계획이 일치하지 않습니다.
  • 100017
    설명
    공간/저장소 파일 접근이 제한되었습니다.
  • 100018
    설명
    파일이 크기 제한을 초과했습니다.
  • 100019
    설명
    파일 형식이 지원되지 않습니다.
  • 100020
    설명
    Referer 허용되지 않습니다.
  • 100021
    설명
    기능은 Pro 또는 Premium 사용자만 사용할 수 있습니다.
  • 100022
    설명
    기능은 Premium 사용자만 사용할 수 있습니다.
  • 100023
    설명
    인증서 내용이 유효하지 않습니다.
  • 100024
    설명
    인증서와 개인 키가 일치하지 않습니다.
  • 100025
    설명
    이미지 MIME 유형이 유효하지 않습니다.
  • 100026
    설명
    파일 접근 링크가 만료되었습니다.
  • 100027
    설명
    API 호출 횟수가 제한을 초과했습니다.
  • 100028
    설명
    일괄 작업은 유료 사용자만 사용할 수 있습니다.
  • 100029
    설명
    이미지 링크가 유효하지 않습니다.
  • 100030
    설명
    계정이 위반 의심되어 로그인이 금지되었습니다.

SDK

StarDots는 다양한 프로그래밍 언어를 위한 SDK를 제공하여 API와 빠르게 통합할 수 있도록 도와줍니다. 다음 링크에서 SDK를 찾을 수 있습니다:

문제가 발생하면 저희에게 연락주세요