cornflow-core 0.0.5

REST API flask backend components used by cornflow and other REST APIs

Cornflow-core is a library that contains modules to help you create REST APIs in an easier and faster way. It includes a set of modules that can be used to start the creation of your flask REST API and some command line interface commands that let you create a full REST API from a JSONSchema file that represent your data or create a JSONSchema file representing your REST API.

Command line interface generate_from_schema

The cli generate_from_schema allows you to automatically generate models, endpoints and schemas from a JSONSchema. The generated files can then be added to your flask (RestFul) REST API.

How to use?

To start, you need to have a json file containing the schema of the tables you want to create. Let’s assume that this file is stored on your computer as C:/Users/User/instance.json Open the terminal, then run:

generate_from_schema -p C:/Users/User/instance.json -a application_name

The argument application_name will be the prefix of the name used for the generated files, classes and tables. It is an optional argument This command will create a new output/ directory in the folder where is executed, containing three directories models/, schemas/ and endpoints/, in which the new files will be added.

Optional arguments

Output path

Use the -o or --output-path options to set an output path for the files. The directories models/, endpoint/ and schemas/ will be created directly in that direction instead of the ./output/ directory.

Example:

generate_from_schema -p C:/Users/User/instance.json -a application_name --output-path C:/Users/User/output_files

Remove methods

By default, two endpoints are created:

• A global endpoint, with three methods:

  • get(), that returns all the element of the table.

  • post(**kwargs), that adds a new row to the table.

• A detail endpoint, with three methods:

  • get(idx), that returns the entry with the given id.

  • put(idx, **kwargs), that updates the entry with the given id with the given data.

  • patch(idx, **kwargs) that patches the entry with the given id with the given oatch.

  • delete(idx), that deletes the entry with the given id.

If one or several of those methods are not necessary, the option --remove-methods or -r allows to not generate some of those methods.

Example:

generate_from_schema -p C:/Users/User/instance.json -a application_name --remove-methods get-list -r delete-detail

In that example, for each table, the detail endpoint will not contain the delete() method and the list endpoint will not contain the get() method. The choices for this method are get-list, post-list, get-detail, put-detail, delete-detail and patch-detail.

One table

By default, the module accepts schemas that contain several tables at once (see for example the instance schema for the rostering application, in cornflow-dags). If you only need to create one table, the schema can also have the following format:

{
  "type": "array",
  "description": "Table with the employee master information",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "description": "The unique identifier for each employee.",
        "type": "integer",
      },
      "name": {
        "description": "The name of each employee.",
        "type": "string",
      },
    },
    "required": [
      "id",
      "name",
    ]
  }
}

that is, the schema is simply the description of the table. In that case, you can use the --one option to indicate the name of the table. If not, the generated table will be called {application_name}_data by default.

Example:

generate_from_schema -p C:/Users/User/instance.json -a application_name --one table_name

In that case, only one table will be created.

Notes

Primary keys

If your table contains a field named id, this field will automatically be considered the primary key of the table. If it doesn’t, an autoincrementing column id will be added to the table and id will be set as the primary key of the table.

Foreign keys

If a field is a foreign key to another table, this can be indicated in the schema. You only need to add the property foreign_key in the information about the property. Its value must have the format table_name.key, table_name being the name of the table the attributes refers to, and key being the name of the foreign key in the original table. For example, if the table employee has a id_job property that is a foreign_key referring to the property id of the table jobs, then the property id_job can be described as follows:

{
    ...,
    "id_job": {
        "type": "integer",
        "description": "The id. of the job",
        "foreign_key": "jobs.id"
    },
    ...
}

If the property foreign_key is left empty, it is assumed that the key is not a foreign key.

Module schema_from_models

The cli schema_from_models allows you to automatically generate a JSONSchema based on a set of models.

How to use?

To start, you need to have a directory containing the SQLAlchemy models. Let’s assume that this directory is stored on your computer as C:/Users/User/models Open the terminal and run:

schema_from_models -p C:/Users/User/models

This command will create a new output_schema.json directory in the directory from where it was executed, containing the generated schema.

Optional arguments

Output path

Specify an output path using the argument -o or --output_path.

Ignore files

By default, all the python files that do not contain models will be ignored. However, if you need to specify that some model files need to be ignored, you can use the -i or --ignore-files option. This option takes as arguments the name of the files to ignore with their extension. Example:

schema_from_models -p C:/Users/User/models --ignore-files instance.py -i execution.py