CLI: a command to create a new service

[bajtos]

This is a follow-up for #1267

There should be a new CLI command for creating services, this command should:

• (MUST HAVE) Create the datasource.
• (MUST HAVE) Create any artifacts needed to register the service with the app for dependency injection. Leverage the Service booter implemented by Sugar API for registering services + automated registration via boot #1439
• (SHOULD HAVE) Create any artifacts needed to write an integration test for the service as I shown in Make services easy to test + docs #1311.
• (NICE TO HAVE) Ideally, include a scaffolding making it easier for app developers to start writing smoke tests.

[raymondfeng]

Create the datasource.

Yes.

Create any artifacts needed to register the service with the app for dependency injection. This may require us to implement support for services in @loopback/boot.

The only artifact we need for service proxy is the data source for a service-oriented connector. I don't see the immediate requirement to make service declarative beyond the data source itself.

[bajtos]

The only artifact we need for service proxy is the data source for a service-oriented connector. I don't see the immediate requirement to make service declarative beyond the data source itself.

See the example in #1311. When writing tests of a service proxy, users should not need to bootstrap the full app in order to access the service proxy instance. Ideally, the tests should not need to know how the service proxy is created at all - the creation aspect should be captured in one place only.

import {GeoService} from '../services/geo.service';
import {expect} from '@loopback/testlab';

describe('GeoService', () => {
  let service: GeoService;
  beforeEach(() => service = new GeoService());

  describe('geocode', () => {
    it('returns geo coords for a given address', () => {
      const result = await service.geocode('107 S B St', 'San Mateo', '94401');
      // { lat: 37.5669986, lng: -122.3237495 }
     expect(result.lat).approximately(37.5669986, 0.5);
     expect(result.lng).approximately(-122.3237495, 0.5);
    });
  });
});

[bajtos]

I think this task should wait until #1439 (Sugar API for registering services + automated registration via boot) is done. See the code in examples/todo added by #1347 for a reference implementation that our CLI template should scaffold.

[jannyHou]

cc @strongloop/sq-lb-apex @raymondfeng @hacksparrow @bajtos
The Geo services is added to example/todo and creating/booting a service is also supported now.
I am good with using the story description as acceptance criteria.

Any more comments before getting it ready for estimation?

[virkt25]

So my understanding is that the story is about creating a json/ts datasource file + a *.service.ts file -- assuming we have a template that is known for REST / SOAP services ... which may / may not be known given the models.

[bajtos]

I have slightly updated the issue description to mention that Service booter is already implemented, and also marked the last two items are should-have/nice-to-have.

So my understanding is that the story is about creating a json/ts datasource file + a *.service.ts file -- assuming we have a template that is known for REST / SOAP services ... which may / may not be known given the models.

+1 to create json/ts datasource file (possibly by delegating to lb4 datasource as an implementation detail) and a *.service.ts file.

If it makes the implementation any easier, then I am fine with splitting the process of creating a new service into two steps (two CLI invocations):

• The first to call the existing lb4 datasource.
• The second to call lb4 service. lb4 service can ask for an existing datasource in the first step.

assuming we have a template that is known for REST / SOAP services ... which may / may not be known given the models.

I don't think there is a single template that would work for all REST/SOAP services. I think we should create an empty definition of remote methods and let the user to manually fill in the template afterwards. Isn't this the same we do in LoopBack 3.x? We can help the user by asking for few things that are common to all services, for example a path/URL of a WSDL file for a SOAP service, a base URL for a REST service, etc.

Let's work incrementally and keep the initial CLI implementation simple.

To me, the most important goal is to create a *.service.ts file that's wired with the correct datasource and automatically picked by the application during boot/startup.

@marioestradarosa do you have any opinion on how a CLI command lb4 service should work from the perspective of our users, LB app developers connecting to an external service?

[hacksparrow]

What is a service? A model-like interface to an external API / web service / resource?

Service should be added to the list of "Key concepts".

[bajtos]

@hacksparrow

What is a service? A model-like interface to an external API / web service / resource?

See https://loopback.io/doc/en/lb4/Calling-other-APIs-and-web-services.html

Service should be added to the list of "Key concepts".

+1

could you please create a new story or perhaps open a pull request?

[jannyHou]

• filter the existing datasources to return only the ones for service

• generate the service.ts file

• update the index.ts file

• leave the test templates out of the scope of the story.

[marioestradarosa]

One thing important in services are the remote methods and how we define them locally. I think that having the wsdl on hand, the service generator can inspect and create the methods stated in the wsdl. This can save a lot of time for the app developer.

I believe that for REST based datasources it will be more complicated as there is nothing standard such as the wsdl file, of course there are openAPI endpoints we can use to discover remote methods, but not all REST endpoints uses it.

Moreover, I think that users can be presented a list of remote methods previously inferred from remote or local wsdl so they can choose which ones they would like to include in the service interface.

[raymondfeng]

@marioestradarosa See #1070 (comment).

[marioestradarosa]

To me, the most important goal is to create a *.service.ts file that's wired with the correct datasource and automatically picked by the application during boot/startup.

Yes, that's the final outcome.

See #1070 (comment).

That's excellent @raymondfeng to use the current specs to create/inspect remote openAPI endpoints.

So, for me the most time consuming task is to fill out the remote method signatures and if we can create it for the user would be good. So, we should write the JSON datasource with methods and create the service interface also with these methods, the reamining code is almost similar.

lb4 service myServiceName --wsdl http://url/myws?wsdl --datasourceName testRemoteDS

If the above command installs the service proxy, inspects the wsdl, generates the json file with remote methods and the my-service-name.service.ts with the service interface, that could really help a lot.

However, we can create this PR with the basic first and then a second one with integration for SOAP and REST inferring their methods.

[raymondfeng]

Let's start with the simplest form - a service with OpenAPI spec. LB3 has the lb soap command does service proxy code generation to some extent.

[marioestradarosa]

you mean something like this?

'lb4 service myServiceName --openapi http://url/openapi.json --datasourceName testRemoteDS'

[bajtos]

Let's start with the simplest form - a service with OpenAPI spec.

I am proposing to start with an increment smaller than that.

IMO, this is the minimal useful increment that we should start with:

Create a *.service.ts file that's wired with the correct datasource and automatically picked by the application during boot/startup.

It will allow us to keep the pull request reasonably small. Adding a new generator involves quite a lot of ceremony/boilerplate code which is easier to review when there are no other features (like OpenAPI discovery) included.

Once we have this dummy lb4 service command implemented, we can start looking into more advanced use cases (generate OpenAPI service client, SOAP service client, etc.) and what's even better, we this work can be parallelized (one person can look into OpenAPI, another into SOAP, etc.)

[raymondfeng]

I agree with @bajtos for the incremental stages:

1. Add lb4 service command (similar as lb4 repository except that no model is needed) to generate a weakly typed service proxy backed by a service-oriented datasource (select from a list of existing ones).

2. Enhance lb4 service command with inspection of service specs to generate strongly-typed service proxies and corresponding model definitions.

• openapi/swagger: OAS 3.x/2.x
• soap: wsdl/xsd
• grpc: service/message w/ ProtoBuffer 3.0

[marioestradarosa]

Enhance lb4 service command with inspection of service specs to generate strongly-typed service proxies and corresponding model definitions.
openapi/swagger: OAS 3.x/2.x
soap: wsdl/xsd

@raymondfeng on SOAP section, I have no questions so far. However, do you have an idea what we should do in some cases where the REST end point doesn't have a spec file and the only thing we have is its URL ?

[dhmlau]

@marioestradarosa , the PR #1736 has merged. Is this ticket good to close?

[marioestradarosa]

@dhmlau I believe so. The enhancement of the lb4 service will be done in the following three separate tasks, for simplicity and having all discussions focused on a specific protocol/architecture style to inspect.

• Rest
• Soap
• Grpc

[dhmlau]

@marioestradarosa , thanks. Do you have the follow-up tasks created? I may not have the details to open them :)

[dhmlau]

Per @marioestradarosa , closing this as resolved.

[marioestradarosa]

Enhance lb4 service command with inspection of service specs to generate strongly-typed service proxies and corresponding model definitions.

openapi/swagger: OAS 3.x/2.x
soap: wsdl/xsd
grpc: service/message w/ ProtoBuffer 3.0

As per @raymondfeng comment above, this is the only thing we have, probably you could help with the soap first as this is the one I want to focus for now? . As @bajtos mentioned also the work on both SOAP and REST can be done in parallel.