Services

Overview

Services - is the main entity that you operate on when working with the code.store platform. These are backends that you, members of your organization, or public users of the code.store platform creates.

One of the key features of our platform is the reuse of services. Since the service doesn't belong to any specific project, you can reuse the services that are available to you.

For convenience, the code.store platform provides the ability to develop your services in various languages:

• TypeScript

Currently, we are actively working on adding support for different languages and frameworks, such as: Go, PHP, Python, Java, C#... so soon you will be able to see support for your particular technology.

Using the CLI or web interface - you can create/edit/update/add to projects/delete your services. Below are examples of how this can be done.

When service is created - the platform automatically deploys it to private and demo environments. For more information about environments, see the Environments section.

private environment - created exclusively for you, with the purpose of developing and testing your service, when the demo - is a public environment, in the context of your organization (or marketplace, if you wish to publish your service in mass and make some money on it)

New Service Creation

In order to create a new service, you must have an account on the code.store platform

Web interface

You can create a new service using the web interface by going to https://app.code.store/services by clicking on the “create service” button located at the bottom of the screen. Fill out the service creation form and click on the CREATE button. After that, the service will be available on the general list on the services page.

It takes some time for the service to be available, in general, the creation process takes less than a few minutes, during which we create a working instance of your future service, collecting an image for you, and deploying it in one of the k8s clusters. We are actively working on the platform and in the future, the process of creating service will take no more than 10 seconds.

CLI

In general, creating a service through the web interface or through the CLI is no different, except for the visual design. Perhaps, as a developer, the way of creating a service using the CLI will be more comfortable for you, since at the stage of creation you will receive more information about what is happening “under the hood”

In order to create a new service, you need to have a pre-installed CLI and be authorized on the code.store platform (see Getting started guide)

First, go to the directory where the folder with the initialization template for your service will be created, for example, let it be your home directory.

cd ~

Then, just execute the service creation command:

cs service:create 

Using the cs service: create command, we initiate the process of creating a service, during which it will be necessary to answer the following questions:

• ? Service name:

• ? What problem are you solving?:

• How do you solve it?:

• Choose business domain using arrow keys

• Specify hashtags

After that, you will see the progress of creating a new service, during which we copy the starting project template, build the image, and deploy it to our k8s cluster.

We are actively working on the platform and in the future, the process of service creation will take only a few seconds.

After successfully creating the service, you will receive a message with links and secrets. Here an example of the output:

Use developer key for private environment: d72e1217-28e8-44bf-9a31-9b220f2e29fc
Your service on private environment is available by this url: https://api.code.store/50de255b0812453e9ae3cec6ee7e8b83/graphql
Your service on demo environment is available by this url: https://api.code.store/ffc8b48e5c1d45e2b48d5c7b91ca6748/graphql

YOUR_SERVICE_NAME
├── codestore.yaml
├── package.json
└── src
    ├── data
    │   ├── entities
    │   └── migrations
    ├── resolvers
    │   ├── mutations
    │   ├── queries
    │   │   └── helloWorld.ts
    │   └── resolvers.ts
    └── schema.graphql

You can check its performance by following the links that you received when creating the service. These links lead to the GraphQL playground, which is available by default for every new service.

Please note that your service was deployed on two private and demo environments at once. For more information about environments, see the Environments section.

You also receive a developer key for your private environment. This key must be used each time when you call your service in a private environment, just by adding HEADER “x-user-authorization”. In order to restrict access to a service that is under active development, you should use an authorization. The built-in mechanism for accessing and authorizing your services can be found in the Access and Authorization section.

After creating the service - the code is available at the same dir, where you execute cs service:create command, in a new folder, which has the name of your service, that you specified while creating.

File Structure

The root directory contains two files and one folder:

• codestore.yaml – the file that contains the configurations of your service, you can learn more about the settings on the service configuration page

• package.json – it is a standard NPM configuration file. Feel free and add any NPM packages you like using npm install {packageName};

• src/ – this is where all the source code lives.

Let's dive into the src/ directory:

• schema.graphql – contains a GraphQL schema of your service;

• data/ – folder that contains entities, which required to work with the database.

• data/entities – this directory contains TypeORM entities. You can automatically generate TypeScript classes for your database tables using cs generate:models -p src/data command;

• data/migrations – this directory contains SQL migrations for your service;

• resolvers/ – this is where your business logic lives.

• resolvers/query andresolvers/mutation – resolvers and mutations serve two purposes: connect your GraphQL objects to data in the database and is a place where you implement any additional business logic.

Most of the things for working with the database, such as migrations, Typeorm entities, can be generated using the generator built into the CLI. The principles of models and migrations generation can be found in the Generation section.

Local development

To simplify the local launch of the service - available simple command: cs dev. After executing, on the backstage will be installed all dependencies (npm i), compiled typescript code (tsc), validating GraphQL schema, queries, and mutations, and applied middleware functions.

Note, if the service uses a database, you need to provide the credentials (login, password, database, port, host) for the database object in the codestore.yaml file. Here an example of the local configuration of codestore.yaml:

# ./codestore.yaml

localConfiguration:
 database:
   port: 5432
   database: my-local-database
   password: password
   username: postgres
   host: localhost

Running this command will install all the necessary dependencies with package.json, compile the code (for this we use tsc), validated GraphQL schema.

After successful execution of the command, the service will be available at the link: http://localhost:3000/grpahql Please, make sure that 3000 port is free, before launching command.

Below is as an example of successful execution cs dev command

2020-11-02T20:27:34.930Z [NPM] Installing dependencies 
2020-11-02T20:28:00.848Z [TypeScript] Compiling typescript code 
2020-11-02T20:28:04.570Z [GraphQL] Validating schema 
2020-11-02T20:28:04.589Z [GraphQL] Validating queries and mutations 
2020-11-02T20:28:05.856Z [INFO] Starting development server 
2020-11-02T20:28:05.856Z [Bootstrap] Start bootstrapping the application 
2020-11-02T20:28:05.864Z [Database] Connecting to database 
2020-11-02T20:28:05.983Z [Database] Successfully connected 
2020-11-02T20:28:05.985Z [GqlLoader] Loaded queries: helloWorld 
2020-11-02T20:28:05.997Z [RestLoader] Loaded REST handlers: 
2020-11-02T20:28:05.999Z [Bootstrap] GraphQL is available on: http://localhost:3000/graphql 

Service update

Create a new version

Each service from time to time has to roll our new updates. After changes have been made to your service code - we can roll updates to the private environment. To publish a new version you have to use cs push command.

If you roll new updates and don't update your version at your packgaje.json, we will automatically increment the path version (x.y.Z). We recommend follow SemVer standard and update your service version each time when you push updates.

Displayed service version will take from package.json file.

Following our environment concept, by default, the service will be updated on the private environment.

Pushing updates

Using the cs push command - you publish your changes. When executing this command, you will specify release notes, which will serve as information about what exactly changes have been made. Below is as an example of successful execution cs push command:

 Please enter release notes (semicolon separated)
 Notes: note

✔ Compiling your code
✔ Validating schema
✔ Preparing the service code for upload

As you can see, on backstage we compiling your code using tsc, and validating the schema, so you can be sure - changes you made are valid. If something went wrong - you will see an error message and pushing will be interrupted.

In general, working with the cs push command can be thought of as a git command with validation and pre-compilation of your code. In the future, we will provide access to your code through the GIT repository, but at the moment, you need to take care of this by yourself.

Promote new version to Demo environment

After pushing changes to Private environment, in order to further distribute a new version of the service to projects, it becomes necessary to publish the changes. To publish changes just execute cs promote command.

Service promotion from private to demo environment will create a new service version. To learn about environments and versioning concepts follow Environments and Versioning sections.

Validation and compilation

Each time when you push your code using cs push command - we compile and validate your code. If you develop your services using local development using cs dev command - you can be sure that everything will be OK.

Each push of your updates trigger compilation based on tsc (TypeScript compiler) and GraphQL schema validation. If something went wrong - you will receive an error message.

Interfaces

The code.store framework provides the ability to create both REST and GraphQL interfaces.

REST

REST interfaces - is a simple file-system-based routing of REST API endpoints based on Express framework. How to create REST endpoints, handlers, middlewares described in REST section.

GraphQL

GraphQL is an API standard that provides a more efficient, powerful, and flexible alternative to REST. We understand it like no one else and provides an opportunity for full-cycle data management of your GraphQL API. With code.store platform you able to:

• be sure, that you schema and code always valid

• generate database models (TypeORM entities) based on your GraphQL schema

• generate migrations to your PostgreSQL database

• generate handlers to your queries and mutations

How to use GraphQL described in Services - GraphQL section. How to generate models, migrations, resolvers... described in Generation section.

Service info

To display information about your service just execute cs service:info command inside service dir.

Command execution result will be displayed with information about deployed on the demo and private environment service version, deployed date, developer key's and service URL's.

Service: demo_app	demo

              Private                                                         Demo                                                            
version       0.0.1                                                           0.0.1                                                           
deployed      11/12/2020, 10:18:57 AM                                         11/12/2020, 10:18:57 AM                                         
developer key cff7f0fb-8856-48e7-817b-0d83c696b247                                                                                            
url           https://api.code.store/a147ac464fd94f4ea9f430e9f28ba933/graphql https://api.code.store/2f8f2cf0d1e046e1b27dc2d14a357f13/graphql