NDC REST Connector
NDC REST Connector allows you to quickly convert REST APIs to NDC schema and proxy requests from GraphQL Engine v3 to remote services.
The connector can automatically transform OpenAPI 2.0 and 3.0 definitions to NDC schema.
Quick start
Start the connector server at http://localhost:8080 using the JSON Placeholder APIs.
go run . serve --configuration ./rest/testdata/jsonplaceholder
How it works
REST connector uses the NDC REST extension that includes request information.
The connector has request context to transform the NDC request body to REST request and versa.
Configuration
The connector reads config.{json,yaml}
file in the configuration folder. The file contains information about the schema file path and its specification:
files:
- path: swagger.json
spec: openapi2
- path: openapi.yaml
spec: openapi3
trimPrefix: /v1
envPrefix: PET_STORE
methodAlias:
post: create
put: update
- path: schema.json
spec: ndc
trimPrefix
, envPrefix
and methodAlias
options are used to convert OpenAPI by ndc-rest-schema.
Supported specs
openapi3
: OpenAPI 3.0/3.1.
openapi2
: OpenAPI 2.0.
ndc
: NDC REST schema.
The connector can convert OpenAPI to REST NDC schema in runtime. However, it's more flexible and performance-wise to pre-convert them, for example, change better function or procedure names. The connector supports a convert command to do it.
ndc-rest convert -f ./rest/testdata/jsonplaceholder/swagger.json -o ./rest/testdata/jsonplaceholder/schema.json --spec openapi2
The convert
command is imported from the NDC REST Schema CLI tool.
Supported content types
application/json
application/x-www-form-urlencoded
application/octet-stream
multipart/form-data
text/*
- Upload file content types, e.g.
image/*
from base64
arguments.
Environment variable template
The connector can replaces {{xxx}}
templates with environment variables. The converter automatically renders variables for API keys and tokens when converting OpenAPI documents. However, you can add your custom variables as well.
Timeout and retry
The global timeout and retry strategy can be configured in the settings
object.
settings:
timeout: 30
retry:
times: 2
# delay between each retry in milliseconds
delay: 1000
httpStatus: [429, 500, 502, 503]
Authentication
The current version supports API key and Auth token authentication schemes. The configuration is inspired from securitySchemes
with env variables
See this example for more context.