Datasette 1.0a33: 작은 URL 파라미터가 1.0의 기준을 만든다

Datasette 1.0a33은 정식 1.0이 아닌 알파 릴리스다. 그럼에도 가볍게 넘길 업데이트는 아니다. Datasette 1.0의 오래된 과제 중 하나인 “안정적이고 완전히 문서화된 JSON API”에 가까워지도록, API 응답을 구성하는 방식을 한 단계 정리했기 때문이다.¹

핵심은 ?_extra= 패턴의 확장이다. 이 작은 URL 파라미터는 Datasette이 앞으로 어떤 API를 지향하는지 보여준다. 기본 응답은 작게 유지하고, 추가 정보는 호출자가 명시적으로 요청하게 만드는 방향이다.

?_extra=가 해결하려는 문제

?_extra=는 JSON 응답에 포함할 추가 정보를 지정하는 URL 파라미터다. 이 패턴은 Datasette 1.0a3에서 도입됐고, 1.0a33에서는 테이블뿐 아니라 행(row)과 쿼리(query) 페이지까지 적용 범위가 넓어졌다.¹

이 변화가 중요한 이유는 기존 0.x API의 성격과 관련이 있다. 이전 API는 응답에 많은 정보를 기본으로 담는 경우가 있었고, 그 과정에서 실제로 쓰이지 않을 데이터를 만들기 위해 추가 SQL 쿼리가 실행될 수도 있었다.¹

처음에는 풍부한 응답이 편리해 보인다. 하지만 시간이 지나면 모든 필드가 클라이언트와 서버 사이의 암묵적 계약이 된다. 서버는 응답을 바꾸기 어려워지고, 클라이언트는 필요 없는 데이터까지 계속 받아야 한다.

Datasette 1.0a33의 접근은 반대다. 기본 JSON은 가볍게 두고, count, columns, metadata, database_color 같은 부가 정보는 필요한 경우에만 ?_extra=로 요청한다.¹

문서화된 선택지가 API를 안정시킨다

이번 릴리스에서 눈여겨볼 부분은 기능 확장만이 아니다. ?_extra= 패턴에 대한 문서가 작성됐고, 각 extra 항목에는 실제 Datasette 인스턴스에서 캡처한 예시 출력도 제공된다.¹

API에서 문서화는 단순한 부가 작업이 아니다. 특히 1.0을 앞둔 프로젝트에서는 “무엇을 안정적인 계약으로 볼 것인가”를 정하는 과정에 가깝다. 어떤 값이 기본 응답에 포함되는지, 어떤 값은 명시적으로 요청해야 하는지 분리해야 클라이언트 코드도 예측 가능해진다.

따라서 1.0a33의 의미는 “옵션이 몇 개 늘었다”가 아니다. Datasette의 JSON API가 기본값과 확장값을 구분하고, 그 구분을 문서화된 방식으로 제공하기 시작했다는 데 있다.

최근 알파 릴리스 흐름 속의 1.0a33

Datasette 1.0의 안정 릴리스는 오랫동안 준비되어 왔다. 최근 알파 릴리스들은 새 기능을 추가하는 동시에, 1.0에서 유지할 사용 방식과 경계를 정리해 왔다.

예를 들어 1.0a31은 권한이 있는 사용자가 데이터베이스에 쓰기 SQL 쿼리를 실행할 수 있게 했고, 기존 canned queries를 stored queries로 이름을 바꾸며 저장 기능을 제공했다.² 1.0a30은 인스턴스 안에서 빠르게 이동할 수 있는 Jump menu를 도입했으며, 이 메뉴는 플러그인이 확장하고 커스터마이즈할 수 있다.² 1.0a27은 폼과 API 통합을 단순화하는 방향으로 CSRF 보호 동작을 변경했다.²

이 흐름에서 1.0a33은 “데이터를 어떻게 안정적으로 읽게 할 것인가”에 초점을 맞춘 릴리스로 볼 수 있다. Datasette을 단순한 웹 UI가 아니라 SQLite 데이터베이스 위의 JSON API 계층으로 사용하는 팀이라면 특히 주목할 만하다.

지금 확인할 것

1.0a33은 여전히 알파 릴리스다. 운영 환경의 장기 계약으로 바로 받아들이기보다는, 앞으로의 1.0 API 방향을 미리 점검하는 기준으로 보는 편이 안전하다.

실무적으로는 다음을 확인해볼 수 있다.

• 기존 클라이언트가 JSON 응답의 어떤 필드에 의존하는지

• 기본 응답에 없어도 되는 데이터를 받고 있지는 않은지

• ?_extra=로 명시적으로 요청해야 할 정보가 무엇인지

• 플러그인이나 자동화 코드가 행, 쿼리, 테이블 API 응답을 어떻게 해석하는지

결론은 분명하다. Datasette 1.0a33의 핵심은 기능의 양이 아니라 API 설계의 방향이다. 기본은 작게, 확장은 명시적으로, 동작은 문서화해서 제공한다. 오래 유지될 API라면 이 기준이 새 기능보다 더 중요하다.

참고

¹Datasette 1.0a33 with JSON extras in the API

²Datasette News and Blog