# KO Service OpenAPI
KO Service interfaces are described using the OpenAPI (opens new window) specification. This specification defines the path(s) to the service, the request and response scheme and much more. Here we will briefly describe the minimal information needed to describe a KO Service. You can write OpenAPI definitions in YAML or JSON, our templates in KGrid CLI and our examples all use the YAML format, we found the format easier and more concise.
The following describes the basic structure of OpenAPI 3.0 definition. We will use the JS Simple V1.0 (opens new window) OpenAPI 3.0 definition for this example.
Define the version of the OpenAPI Specification and basic information about this API
openapi: 3.0.2 info: version: '1.0' title: 'Hello, world' description: An example of simple Knowledge Object license: name: GNU General Public License v3 (GPL-3) url: >- https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)#fulltext contact: name: KGrid Team email: firstname.lastname@example.org url: 'http://kgrid.org'
The servers section specifies the API server and base URL. for KO Services we use the Archival Resource Key (opens new window) (ark id) which is /naan/name. Using the ark id ensures the paths are unique.
... servers: - url: /js/simple description: Hello world
The paths section defines individual endpoints (paths) in your API. Currently KO Service activation support the POST HTTP method and GET using the resource adapter.
... paths: /welcome: post: tags: - KO Endpoints description: Welcome. operationId: welcome
# Request Body
The requestBody keyword describes the body content and media type. KO services use json inputs. The json format is defined in the input scheme components section of the definition.
... requestBody: description: inputs required: true content: application/json: schema: $ref: '#/components/schemas/input'
Here is the input json definition with type and examples.
... components: schemas: input: required: - name properties: name: type: string x-kgrid-label: 'Please enter your name' x-kgrid-unit: '' example: Bob
To response definition is categorized by status code. The content defines the type and format via a scheme output.
... responses: '200': description: response content: application/json: schema: $ref: 'https://demo.kgrid.org/schemas/openapischemas.yaml#/components/schemas/genericresponse'