The ERIGrid 2.0 middleware API OpenAPI Definition

If you are using this code for research purposes, especially for your publication, please do not forget to cite one of these papers.

console @INPROCEEDINGS{10542755, author={Rajkumar, Vetrivel and Silano, Giuseppe and Gehrke, Oliver and Vogel, Steffen and Widl, Edmund and Paludetto, Gabriele and Rikos, Evangelos and Zerihun, Tesfaye Amare and Ştefanov, Alexandru and Palensky, Peter and Strasser, Thomas I.}, booktitle={2024 12th Workshop on Modeling and Simulation of Cyber-Physical Energy Systems (MSCPES)}, title={Laboratory Middleware for the Cyber-Physical Integration of Energy Research Infrastructures}, year={2024}, volume={}, number={}, pages={1-5}, doi={10.1109/MSCPES62135.2024.10542755}}

Working on your OpenAPI Definition

Install

1. Install Node JS.
2. Clone this repo and run npm install in the repo root.

Usage

npm start

Starts the reference docs preview server.

npm run build

Bundles the definition to the dist folder.

npm test

Validates the definition.

Contribution Guide

Below is a sample contribution guide. The tools in the repository don't restrict you to any specific structure. Adjust the contribution guide to match your own structure. However, if you don't have a structure in mind, this is a good place to start.

Update this contribution guide if you adjust the file/folder organization.

The .redocly.yaml controls settings for various tools including the lint tool and the reference docs engine. Open it to find examples and read the docs for more information.

Schemas

Adding Schemas

1. Navigate to the openapi/components/schemas folder.
2. Add a file named as you wish to name the schema.
3. Define the schema.
4. Refer to the schema using the $ref (see example below).

Example Schema

This is a very simple schema example: yaml type: string description: The resource ID. Defaults to UUID v4 maxLength: 50 example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21 This is a more complex schema example: ``yaml type: object properties: id: description: The customer identifier string readOnly: true allOf: - $ref: ./ResourceId.yaml websiteId: description: The website's ID allOf: - $ref: ./ResourceId.yaml paymentToken: type: string writeOnly: true description: | A write-only payment token; if supplied, it will be converted into a payment instrument and be set as thedefaultPaymentInstrument. The value of this property will override thedefaultPaymentInstrument` in the case that both are supplied. The token may only be used once before it is expired. defaultPaymentInstrument: $ref: ./PaymentInstrument.yaml createdTime: description: The customer created time allOf: - $ref: ./ServerTimestamp.yaml updatedTime: description: The customer updated time allOf: - $ref: ./ServerTimestamp.yaml tags: description: A list of customer's tags readOnly: true type: array items: $ref: ./Tags/Tag.yaml revision: description: > The number of times the customer data has been modified.

  The revision is useful when analyzing webhook data to determine if the
  change takes precedence over the current representation.
type: integer
readOnly: true

_links: type: array description: The links related to resource readOnly: true minItems: 3 items: anyOf: - $ref: ./Links/SelfLink.yaml - $ref: ./Links/NotesLink.yaml - $ref: ./Links/DefaultPaymentInstrumentLink.yaml - $ref: ./Links/LeadSourceLink.yaml - $ref: ./Links/WebsiteLink.yaml _embedded: type: array description: >- Any embedded objects available that are requested by the expand querystring parameter. readOnly: true minItems: 1 items: anyOf: - $ref: ./Embeds/LeadSourceEmbed.yaml

```

Using the $ref

Notice in the complex example above the schema definition itself has $ref links to other schemas defined.

Here is a small excerpt with an example:

yaml defaultPaymentInstrument: $ref: ./PaymentInstrument.yaml

The value of the $ref is the path to the other schema definition.

You may use $refs to compose schema from other existing schema to avoid duplication.

You will use $refs to reference schema from your path definitions.

Editing Schemas

1. Navigate to the openapi/components/schemas folder.
2. Open the file you wish to edit.
3. Edit.

Paths

Adding a Path

1. Navigate to the openapi/paths folder.
2. Add a new YAML file named like your URL endpoint except replacing / with @ and putting path parameters into curly braces like {example}.
3. Add the path and a ref to it inside of your openapi.yaml file inside of the openapi folder.

Example addition to the openapi.yaml file: yaml '/customers/{id}': $ref: './paths/customers@{id}.yaml'

Here is an example of a YAML file named customers@{id}.yaml in the paths folder:

yaml get: tags: - Customers summary: Retrieve a list of customers operationId: GetCustomerCollection description: | You can have a markdown description here. parameters: - $ref: ../components/parameters/collectionLimit.yaml - $ref: ../components/parameters/collectionOffset.yaml - $ref: ../components/parameters/collectionFilter.yaml - $ref: ../components/parameters/collectionQuery.yaml - $ref: ../components/parameters/collectionExpand.yaml - $ref: ../components/parameters/collectionFields.yaml responses: '200': description: A list of Customers was retrieved successfully headers: Rate-Limit-Limit: $ref: ../components/headers/Rate-Limit-Limit.yaml Rate-Limit-Remaining: $ref: ../components/headers/Rate-Limit-Remaining.yaml Rate-Limit-Reset: $ref: ../components/headers/Rate-Limit-Reset.yaml Pagination-Total: $ref: ../components/headers/Pagination-Total.yaml Pagination-Limit: $ref: ../components/headers/Pagination-Limit.yaml Pagination-Offset: $ref: ../components/headers/Pagination-Offset.yaml content: application/json: schema: type: array items: $ref: ../components/schemas/Customer.yaml text/csv: schema: type: array items: $ref: ../components/schemas/Customer.yaml '401': $ref: ../components/responses/AccessForbidden.yaml x-code-samples: - lang: PHP source: $ref: ../code_samples/PHP/customers/get.php post: tags: - Customers summary: Create a customer (without an ID) operationId: PostCustomer description: Another markdown description here. requestBody: $ref: ../components/requestBodies/Customer.yaml responses: '201': $ref: ../components/responses/Customer.yaml '401': $ref: ../components/responses/AccessForbidden.yaml '409': $ref: ../components/responses/Conflict.yaml '422': $ref: ../components/responses/InvalidDataError.yaml x-code-samples: - lang: PHP source: $ref: ../code_samples/PHP/customers/post.php

You'll see extensive usage of $refs in this example to different types of components including schemas.

You'll also notice $refs to code samples.

Code samples

1. Navigate to the openapi/code_samples folder.
2. Navigate to the <language> (e.g. PHP) sub-folder.
3. Navigate to the path folder, and add ref to the code sample.

You can add languages by adding new folders at the appropriate path level.

More details inside the code_samples folder README.

Funding acknowledgement

The development of JRA3.1 API has been supported by the ERIGrid 2.0 project of the H2020 Programme under Grant Agreement No. 870620