OneAsset Developer Guide

목차

1. 01인증면 구분
2. 02Base URL과 환경변수
3. 03API Key 발급 흐름
4. 04Asset 업로드 요청
5. 05업로드 처리 흐름
6. 06Asset key 규칙
7. 07응답 필드와 재접근 URL
8. 08상태 조회와 status 의미
9. 09Asset 목록/상세/삭제
10. 10헬스체크
11. 11에러 처리

1. 인증면 구분

Authorization: Bearer {cognito_jwt}

X-OneAsset-Api-Key: {raw_api_key}

2. Base URL과 환경변수

프론트는 `NEXT_PUBLIC_API_BASE_URL`을 기준으로 Dashboard API를 호출합니다. Developer API를 호출하는 외부 서버도 같은 백엔드 origin을 사용하되, 인증 헤더만 `X-OneAsset-Api-Key`로 바꿉니다.

3. API Key 발급 흐름

1. 01Dashboard에서 Google/Cognito로 로그인합니다.
2. 02POST /api/projects로 프로젝트를 생성합니다.
3. 03POST /api/projects/{projectId}/api-keys로 API Key를 발급합니다.
4. 04응답의 apiKey raw value는 발급 직후 한 번만 복사합니다.
5. 05이후 목록에서는 raw key가 아니라 prefix/status만 확인합니다.

4. Asset 업로드 요청

실제 컨트롤러는 `POST /v1/assets`에서 multipart/form-data를 받습니다. `file`은 필수이고, `key`, `fileName`은 선택입니다.

curl -X POST https://api.oneasset.example/v1/assets \
  -H "X-OneAsset-Api-Key: oa_live_..." \
  -F "file=@hero.png" \
  -F "key=products/main/hero.png" \
  -F "fileName=hero.png"

const form = new FormData();
form.append("file", fileBlob, "hero.png");
form.append("key", "products/main/hero.png");
form.append("fileName", "hero.png");

const response = await fetch(`${process.env.ONEASSET_API_URL}/v1/assets`, {
  method: "POST",
  headers: {
    "X-OneAsset-Api-Key": process.env.ONEASSET_API_KEY,
  },
  body: form,
});

const result = await response.json();
const asset = result.data;

// 실제 이미지 재접근에는 asset.deliveryUrl을 사용합니다.
console.log(asset.deliveryUrl);

5. 업로드 처리 흐름

6. Asset key 규칙

7. 응답 필드와 재접근 URL

응답의 `key`는 사용자 논리 경로이고, `storageKey`는 S3 내부 경로입니다. 재접근 URL은 `deliveryUrl`을 사용합니다. 백엔드 환경변수 `ONEASSET_DELIVERY_BASE_URL`이 비어 있으면 `deliveryUrl`은 null입니다.

{
  "success": true,
  "data": {
    "assetId": "f88dcad8-020c-4ed5-bda9-6c078e52a819",
    "key": "products/main/hero.png",
    "storageKey": "projects/{projectId}/products/main/hero.png",
    "originalFileName": "hero.png",
    "contentType": "image/png",
    "sizeBytes": 125432,
    "status": "PROCESSING",
    "deliveryUrl": "https://cdn.example.com/projects/{projectId}/products/main/hero.png",
    "createdAt": "2026-07-21T17:10:00"
  },
  "error": null
}

8. 상태 조회와 status 의미

현재 실제 상태 조회는 별도 `/status` path가 아니라`GET /v1/assets?key={key}`입니다. 같은 endpoint가 상세 metadata와 status를 함께 반환합니다.

curl "https://api.oneasset.example/v1/assets?key=products/main/hero.png" \
  -H "X-OneAsset-Api-Key: oa_live_..."

async function waitUntilReady(key) {
  for (let attempt = 0; attempt < 10; attempt += 1) {
    const res = await fetch(
      `${process.env.ONEASSET_API_URL}/v1/assets?key=${encodeURIComponent(key)}`,
      { headers: { "X-OneAsset-Api-Key": process.env.ONEASSET_API_KEY } },
    );
    const { data } = await res.json();

    if (data.status === "READY") return data.deliveryUrl;
    if (data.status === "FAILED") throw new Error("Asset processing failed.");

    await new Promise((resolve) => setTimeout(resolve, 1500));
  }

  throw new Error("Asset is still processing.");
}

9. Asset 목록, 상세, 삭제

GET /v1/assets
X-OneAsset-Api-Key: oa_live_...

GET /v1/assets?key=products/main/hero.png
X-OneAsset-Api-Key: oa_live_...

DELETE /v1/assets?key=products/main/hero.png
X-OneAsset-Api-Key: oa_live_...

[
  { "key": "users/123/profile.png", "status": "READY" },
  { "key": "users/123/banner.png", "status": "READY" },
  { "key": "products/iphone/main.png", "status": "PROCESSING" }
]

users
  123
    profile.png
    banner.png
products
  iphone
    main.png

10. 헬스체크

백엔드 SecurityConfig 기준 `/actuator/health`는 인증 없이 허용됩니다. 배포/모니터링에서는 이 endpoint로 API 프로세스와 actuator 상태를 확인합니다.

curl https://api.oneasset.example/actuator/health

// typical Spring Boot response
{
  "status": "UP"
        }

11. Dashboard API 엔드포인트

12. Developer API 엔드포인트

13. 에러 처리

OneAsset API는 `success: false`와 `error.code`를 내려줍니다. 프론트는 code/status를 기준으로 inline error, page error, retry, login redirect로 변환합니다.