Skip to content

Commit dabd559

Browse files
rahil-crahil-c
committed
Add open api REST spec for XTable Service
1 parent 18956f6 commit dabd559

File tree

5 files changed

+386
-0
lines changed

5 files changed

+386
-0
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,6 @@ demo/jars/*
4343
demo/notebook/.ipynb_checkpoints/*
4444
my_config.yaml
4545
my_config_catalog.yaml
46+
47+
# REST generated models
48+
spec/generated

‎spec/Makefile

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
# Licensed to the Apache Software Foundation (ASF) under one
19+
# or more contributor license agreements…
20+
# (your license header…)
21+
22+
PYTHON := python3
23+
VENV_DIR := .venv
24+
PIP := $(VENV_DIR)/bin/pip
25+
VALIDATOR := $(VENV_DIR)/bin/openapi-spec-validator
26+
SPEC := rest-service-open-api.yaml
27+
28+
# Configuration for model generation
29+
GEN_DIR := generated
30+
MODEL_PKG := org.apache.xtable.service.models
31+
32+
.PHONY: all venv install lint clean clean-models
33+
34+
all: lint
35+
36+
# Create venv if it doesn't exist
37+
venv:
38+
@echo "→ creating virtualenv in $(VENV_DIR)…"
39+
$(PYTHON) -m venv $(VENV_DIR)
40+
@echo "→ upgrading pip…"
41+
$(PIP) install --upgrade pip
42+
43+
# Install requirements into venv
44+
install: venv
45+
@echo "→ installing validator…"
46+
$(PIP) install -r requirements.txt
47+
48+
# Validate your OpenAPI spec
49+
lint: install
50+
@echo "→ linting $(SPEC)…"
51+
$(VALIDATOR) --errors all $(SPEC)
52+
53+
# Remove the virtualenv
54+
clean:
55+
@echo "→ removing $(VENV_DIR)…"
56+
rm -rf $(VENV_DIR)
57+
58+
# Generate Java model classes from OpenAPI spec
59+
generate-models:
60+
@echo "→ generating Java model classes from $(SPEC)…"
61+
openapi-generator generate \
62+
-i $(SPEC) \
63+
-g java \
64+
-o $(GEN_DIR) \
65+
--model-package $(MODEL_PKG) \
66+
--global-property models,modelTests=false,modelDocs=false
67+
@echo "→ models generated in $(GEN_DIR)/src/main/java/$(subst .,/,$(MODEL_PKG))"
68+
69+
# Remove all generated model classes
70+
clean-models:
71+
@echo "→ removing generated models in $(GEN_DIR)…"
72+
rm -rf $(GEN_DIR)

‎spec/README.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
<!--
2+
- Licensed to the Apache Software Foundation (ASF) under one
3+
- or more contributor license agreements. See the NOTICE file
4+
- distributed with this work for additional information
5+
- regarding copyright ownership. The ASF licenses this file
6+
- to you under the Apache License, Version 2.0 (the
7+
- "License"); you may not use this file except in compliance
8+
- with the License. You may obtain a copy of the License at
9+
-
10+
- http://www.apache.org/licenses/LICENSE-2.0
11+
-
12+
- Unless required by applicable law or agreed to in writing,
13+
- software distributed under the License is distributed on an
14+
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
- KIND, either express or implied. See the License for the
16+
- specific language governing permissions and limitations
17+
- under the License.
18+
-->
19+
20+
# Open API spec
21+
22+
The `rest-service-open-api.yaml` defines the api contract for running table format conversion using XTable's REST service.
23+
This spec is still under active development and is subject to changes.
24+
25+
## Lint
26+
27+
To make sure that the open-api definition is valid, you can run the `lint` command:
28+
29+
This will first run `make install`, which in turn will create the venv (if needed) and install openapi-spec-validator
30+
```sh
31+
make lint
32+
```
33+
34+
if you want to wipe out the venv and start fresh run make clean
35+
```sh
36+
make clean
37+
```
38+
39+
## Generate
40+
41+
Note: You’ll need the OpenAPI Generator CLI installed and on your `PATH`. You can install it using Homebrew:
42+
```sh
43+
brew install openapi-generator
44+
```
45+
Then to generate the java models from the open-api spec, you can run the `generate-models` command.
46+
47+
```sh
48+
make generate-models
49+
```
50+
If you would to remove the generated models, you can run the `clean-models` command:
51+
```sh
52+
make clean-models
53+
```

‎spec/requirements.txt

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
openapi-spec-validator==0.7.1

‎spec/rest-service-open-api.yaml

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one or more
3+
# contributor license agreements. See the NOTICE file distributed with
4+
# this work for additional information regarding copyright ownership.
5+
# The ASF licenses this file to You under the Apache License, Version 2.0
6+
# (the "License"); you may not use this file except in compliance with
7+
# the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
#
17+
openapi: 3.0.3
18+
info:
19+
title: XTable REST Service API
20+
license:
21+
name: Apache 2.0
22+
url: https://www.apache.org/licenses/LICENSE-2.0.html
23+
version: 0.0.1
24+
description: |
25+
A REST API for initiating metadata conversion using Apache XTable. Note this spec is still under active development and is subject to changes.
26+
27+
servers:
28+
- url: "{scheme}://{host}/{prefix}"
29+
description: Server URL when the port can be inferred from the scheme
30+
variables:
31+
scheme:
32+
description: The scheme of the URI, either http or https.
33+
default: https
34+
host:
35+
description: The host address for the specified server
36+
default: localhost
37+
prefix:
38+
description: Optional prefix to be appended to all routes
39+
default: ""
40+
- url: "{scheme}://{host}:{port}/{prefix}"
41+
description: Generic base server URL, with all parts configurable
42+
variables:
43+
scheme:
44+
description: The scheme of the URI, either http or https.
45+
default: https
46+
host:
47+
description: The host address for the specified server
48+
default: localhost
49+
port:
50+
description: The port used when addressing the host
51+
default: "8080"
52+
prefix:
53+
description: Optional prefix to be appended to all routes
54+
default: ""
55+
56+
paths:
57+
/v1/conversion/table:
58+
post:
59+
tags:
60+
- XTable Service API
61+
summary: Initiate XTable's runSync process to convert a source table format to the requested target table formats.
62+
description: |
63+
Reads the source table metadata from storage, converts it to the requested
64+
target formats.
65+
operationId: convertTable
66+
parameters:
67+
- in: header
68+
name: Prefer
69+
description: Use 'respond-async' to request asynchronous processing.
70+
required: false
71+
schema:
72+
type: string
73+
enum:
74+
- respond-async
75+
requestBody:
76+
required: true
77+
content:
78+
application/json:
79+
schema:
80+
$ref: '#/components/schemas/ConvertTableRequest'
81+
responses:
82+
'200':
83+
$ref: '#/components/responses/ConvertTableResponse'
84+
'202':
85+
$ref: '#/components/responses/SubmittedConversionResponse'
86+
'403':
87+
$ref: '#/components/responses/ForbiddenResponse'
88+
'503':
89+
$ref: '#/components/responses/ServiceUnavailableResponse'
90+
default:
91+
$ref: '#/components/responses/ErrorResponse'
92+
93+
/v1/conversion/table/{conversion-id}:
94+
get:
95+
tags:
96+
- XTable Service API
97+
summary: Polls on a conversion-id to see if converting a table has finished.
98+
operationId: getConversionStatus
99+
parameters:
100+
- in: path
101+
name: conversion-id
102+
required: true
103+
schema:
104+
type: string
105+
responses:
106+
'200':
107+
$ref: '#/components/responses/ConvertTableResponse'
108+
'202':
109+
description: Still processing; conversion has not yet finished.
110+
'403':
111+
$ref: '#/components/responses/ForbiddenResponse'
112+
'503':
113+
$ref: '#/components/responses/ServiceUnavailableResponse'
114+
default:
115+
$ref: '#/components/responses/ErrorResponse'
116+
117+
components:
118+
schemas:
119+
ConvertTableRequest:
120+
type: object
121+
required:
122+
- source-format
123+
- source-table-name
124+
- source-table-path
125+
- target-formats
126+
properties:
127+
source-format:
128+
type: string
129+
description: Name of the source table format (e.g., "ICEBERG", "HUDI", "DELTA")
130+
source-table-name:
131+
type: string
132+
description: Name of the source table
133+
source-table-path:
134+
type: string
135+
description: Path to the source table's metadata
136+
target-formats:
137+
type: array
138+
items:
139+
type: string
140+
description: List of desired output table formats (e.g., "ICEBERG", "HUDI", "DELTA")
141+
configurations:
142+
type: object
143+
description: Additional configuration key/value pairs (e.g., storage credentials or other service configs)
144+
additionalProperties:
145+
type: string
146+
147+
TargetTable:
148+
type: object
149+
required:
150+
- target-format
151+
- target-metadata-path
152+
properties:
153+
target-format:
154+
type: string
155+
description: Name of the target format (e.g., "ICEBERG", "HUDI", "DELTA")
156+
target-metadata-path:
157+
type: string
158+
description: Path where the converted metadata was written
159+
target-schema:
160+
type: string
161+
description: Schema definition of the converted table
162+
163+
ConvertTableResponse:
164+
type: object
165+
required:
166+
- conversions
167+
properties:
168+
conversions:
169+
type: array
170+
description: A list of converted tables, one per requested format
171+
items:
172+
$ref: '#/components/schemas/TargetTable'
173+
174+
SubmittedConversionResponse:
175+
type: object
176+
properties:
177+
conversion-id:
178+
type: string
179+
description: ID to use when polling for the final result
180+
181+
ErrorModel:
182+
type: object
183+
description: JSON error payload returned in a response with further details on the error
184+
required:
185+
- message
186+
- type
187+
- code
188+
properties:
189+
message:
190+
type: string
191+
description: Human-readable error message
192+
type:
193+
type: string
194+
description: Internal type definition of the error
195+
code:
196+
type: integer
197+
minimum: 400
198+
maximum: 600
199+
description: HTTP response code
200+
stack:
201+
type: array
202+
description: Optional stack trace elements for debugging
203+
items:
204+
type: string
205+
206+
responses:
207+
ConvertTableResponse:
208+
description: Successful conversion result
209+
content:
210+
application/json:
211+
schema:
212+
$ref: '#/components/schemas/ConvertTableResponse'
213+
214+
SubmittedConversionResponse:
215+
description: Request accepted for asynchronous processing
216+
content:
217+
application/json:
218+
schema:
219+
$ref: '#/components/schemas/SubmittedConversionResponse'
220+
221+
ForbiddenResponse:
222+
description: Caller does not have permission to perform this operation
223+
content:
224+
application/json:
225+
schema:
226+
$ref: '#/components/schemas/ErrorModel'
227+
228+
ServiceUnavailableResponse:
229+
description: Conversion service is temporarily unavailable
230+
content:
231+
application/json:
232+
schema:
233+
$ref: '#/components/schemas/ErrorModel'
234+
235+
ErrorResponse:
236+
description: Unexpected error
237+
content:
238+
application/json:
239+
schema:
240+
$ref: '#/components/schemas/ErrorModel'

0 commit comments

Comments
 (0)