// Copyright (c) 2019, 2023 IBM Corporation and others. // Licensed under Creative Commons Attribution-NoDerivatives // 4.0 International (CC BY-ND 4.0) // https://creativecommons.org/licenses/by-nd/4.0/ // // Contributors: // IBM Corporation :projectid: rest-client-angular :page-layout: guide-multipane :page-duration: 20 minutes :page-description: Explore how to access a simple RESTful web service and consume its resources with Angular in Open Liberty. :page-essential: false :page-guide-catagory: none :page-permalink: /guides/{projectid} :page-releasedate: 2019-06-21 :page-related-guides: ['rest-intro', 'rest-client-java', 'rest-client-angularjs'] :page-seo-title: Consuming a RESTful Java web service with Angular :page-seo-description: A getting started tutorial with examples on how to access a RESTful Java microservice and consume its resources using the Angular framework. :common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/prod :source-highlighter: prettify :guide-author: Open Liberty = Consuming a RESTful web service with Angular
[.hidden] NOTE: This repository contains the guide documentation source. To view the guide in published form, view it on the https://openliberty.io/guides/{projectid}.html[Open Liberty website].
Explore how to access a simple RESTful web service and consume its resources with Angular in OpenLiberty.
// ================================================================================================= // Introduction // =================================================================================================
== What you'll learn
https://angular.io[Angular^] is a framework for creating interactive web applications. Angular applications are written in HTML, CSS, and https://www.typescriptlang.org[TypeScript^], a variant of JavaScript. Angular helps you create responsive and intuitive applications that download once and run as a single web page. Consuming REST services with your Angular application allows you to request only the data and operations that you need, minimizing loading times.
You will learn how to access a REST service and deserialize the returned JSON that contains a list of artists and their albums by using an Angular service and the Angular HTTP Client. You will then present this data using an Angular component.
The REST service that provides the artists and albums resource was written for you in advance and responds with the [hotspot]artists.json.
The Angular application was created and configured for you in the frontend directory. It contains the default starter application. There are many files that make up an Angular application, but you only need to edit a few to consume the REST service and display its data.
Angular applications must be compiled before they can be used. The Angular compilation step was configured as part of the Maven build. You can use the start folder of this guide as a template for getting started with your own applications built on Angular and Open Liberty.
// Static guide instruction
ifndef::cloud-hosted[]
You will implement an Angular client that consumes this JSON and displays its contents
at the \http://localhost:9080/app URL.
endif::[]
// Cloud hosted guide instruction ifdef::cloud-hosted[] You will implement an Angular client that consumes this JSON and displays its contents. endif::[]
To learn more about REST services and how you can write them, see https://openliberty.io/guides/rest-intro.html[Creating a RESTful web service^].
// ================================================================================================= // Getting Started // ================================================================================================= [role='command'] include::{common-includes}/gitclone.adoc[]
[role='command'] include::{common-includes}/twyb-intro.adoc[]
// Static guide instruction ifndef::cloud-hosted[] Then, point your browser to the web application root http://localhost:9080/app[http://localhost:9080/app^] to see the following output: endif::[]
// Cloud hosted guide instruction ifdef::cloud-hosted[] Click the following button to visit the web application /app root endpoint: ::startApplication{port="9080" display="external" name="Visit application" route="/app"}
You will see the following output: endif::[]
[role='command'] include::{common-includes}/twyb-end.adoc[]
// ================================================================================================= // Starting the service // =================================================================================================
== Starting the service
Before you begin the implementation, start the provided REST service so that the artist JSON is available to you.
Navigate to the start directory to begin.
// cloud-hosted guide instructions: ifdef::cloud-hosted[]
cd /home/project/guide-rest-client-angular/startendif::[]
[role='command'] include::{common-includes}/devmode-lmp33-start.adoc[]
// Static guide instruction ifndef::cloud-hosted[] You can find your artist JSON at the http://localhost:9080/artists[http://localhost:9080/artists^] URL. endif::[]
// Cloud hosted guide instruction ifdef::cloud-hosted[] You can find your artist JSON by running the following command at a terminal:
curl -s http://localhost:9080/artists | jqendif::[]
// ================================================================================================= // Project configuration // =================================================================================================
== Project configuration
The front end of your application uses Node.js to execute your Angular code. The Maven project is configured for you to install Node.js and produce the production files, which are copied to the web content of your application.
Node.js is server-side JavaScript runtime that is used for developing networking applications. Its convenient package manager, https://www.npmjs.com/[npm^], is used to execute the Angular scripts found in the package.json file. To learn more about Node.js, see the official https://nodejs.org/en/docs/[Node.js documentation^].
The [hotspot=frontend-plugin]frontend-maven-plugin is used to [hotspot=node-resource-install]install the dependencies listed in your package.json file from the npm registry into a folder called node_modules. The node_modules folder is found in your [hotspot=working-dir]working directory. Then, the configuration [hotspot=node-resource-build]produces the production files to the src/main/frontend/src/app directory.
The src/main/frontend/src/angular.json file is defined so that the production build is copied into the web content of your application.
// ================================================================================================= // Creating the root Angular module // =================================================================================================
== Creating the root Angular module
Your application needs a way to communicate with and retrieve resources from RESTful web services. In this case, the provided Angular application needs to communicate with the artists service to retrieve the artists JSON. While there are various ways to perform this task, Angular contains a built-in HttpClientModule that you can use.
Angular applications consist of modules, which are groups of classes that perform specific functions. The Angular framework provides its own modules for applications to use. One of these modules, the HTTP Client module, includes convenience classes that make it easier and quicker for you to consume a RESTful API from your application.
You will create the module that organizes your application, which is called the root module. The root module includes the Angular HTTP Client module.
app.module.ts file.src/main/frontend/src/app/app.module.tsThe [hotspot=importHttpClientModule]HttpClientModule imports the class into the file. By using the [hotspot=atNgModule]@NgModule tag, you can declare a module and organize your dependencies within the Angular framework. The imports array is a declaration array that imports the [hotspot=httpClientModule]HttpClientModule so that you can use the HTTP Client module in your application.
// ================================================================================================= // Creating the Angular component to fetch data // =================================================================================================
== Creating the Angular service to fetch data
You need to create the component that is used in the application to acquire and display data from the REST API. The component file contains two classes: the service, which handles data access, and the component itself, which handles the presentation of the data.
Services are classes in Angular that are designed to share their functionality across entire applications. A good service performs only one function, and it performs this function well. In this case, the ArtistsService class requests artists data from the REST service.
app.component.ts file.src/main/frontend/src/app/app.component.tsThe file imports the [hotspot=importHttpClient]HttpClient class and the [hotspot=importInjectable]Injectable decorator.
The [hotspot=artistsServiceClass]ArtistsService class is defined. While it shares the file of the component class [hotspot=appComponentClass]AppComponent, it can also be defined in its own file. The class is annotated by [hotspot=atInjectable]@Injectable so instances of it can be provided to other classes anywhere in the application.
The class injects an instance of the [hotspot=httpClientInstance]HttpClient class, which it uses to request data from the REST API. It contains the [hotspot=artistsUrl]ARTISTS_URL constant, which points to the API endpoint it requests data from. The URL does not contain a host name because the artists API endpoint is accessible from the same host as the Angular application. You can send requests to external APIs by specifying the full URL. Finally, it implements a [hotspot=fetchArtistsMethod]fetchArtists() method that makes the request and returns the result.
To obtain the data for display on the page, the [hotspot=fetchArtistsMethod]fetchArtists() method tries to use the injected [hotspot=httpInstanceAndAwaitFeatureAndHttpGetAndToPromise]http instance to perform a GET HTTP request to the [hotspot=artistsUrl]ARTISTS_URL constant. If successful, it returns the result. If an error occurs, it prints the error message to the console.
The [hotspot=fetchArtistsMethod]fetchArtists() method uses a feature of JavaScript called [hotspot=asyncFeature]async, [hotspot=httpInstanceAndAwaitFeatureAndHttpGetAndToPromise]await to make requests and receive responses without preventing the application from working while it waits. For the result of the [hotspot=httpInstanceAndAwaitFeatureAndHttpGetAndToPromise]HttpClient.get() method to be compatible with this feature, it must be converted to a Promise by invoking its [hotspot=httpInstanceAndAwaitFeatureAndHttpGetAndToPromise]toPromise() method. APromise is how JavaScript represents the state of an asynchronous operation. If you want to learn more, check out https://promisejs.org[promisejs.org^] for an introduction.
// ================================================================================================= // Defining the component to consume the service // =================================================================================================
== Defining the component to consume the service
Components are the basic building blocks of Angular application user interfaces. Components are made up of a TypeScript class annotated with the [hotspot=atComponent]@Component annotation and the HTML template file (specified by [hotspot=templateUrl]templateUrl) and CSS style files (specified by [hotspot=styleUrls]styleUrls.)
Update the [hotspot=appComponentClass]AppComponent class to use the artists service to fetch the artists data and save it so the component can display it.
app.component.ts file.src/main/frontend/src/app/app.component.ts[role="edit_command_text"]
Replace the entire [hotspot=appComponentClass]AppComponent class along with the [hotspot=atComponent]@Component annotation. Add [hotspot=importOnInitAndAngularCorePackage]OnInit to the list of imported classes at the top.
The [hotspot=providersProperty]providers property on the [hotspot=atComponent]@Component annotation indicates that this component provides the [hotspot=artistsServiceClass]ArtistsService to other classes in the application.
[hotspot=appComponentClass]AppComponent implements [hotspot=onInitInterface]OnInit, which is a special interface called a lifecycle hook. When Angular displays, updates, or removes a component, it calls a specific function, the lifecycle hook, on the component so the component can run code in response to this event. This component responds to the [hotspot=onInitInterface]OnInit event via the [hotspot=ngOnInitMethod]ngOnInit method, which fetches and populates the component's template with data when it is initialized for display. The file imports the [hotspot=importOnInitAndAngularCorePackage]OnInit interface from the [hotspot=importOnInitAndAngularCorePackage]@angular/core package.
[hotspot=artistsClassMember]artists is a class member of type any[] that starts out as an empty array. It holds the artists retrieved from the service so the template can display them.
An instance of the [hotspot=artistsServiceInstanceDeclaration]ArtistsService class is injected into the constructor and is accessible by any function that is defined in the class. The [hotspot=ngOnInitMethod]ngOnInit function uses the [hotspot=artistsServiceInstance]artistsService instance to request the artists data. The [hotspot=fetchArtistsMethod]fetchArtists() method is an async function so it returns a Promise. To retrieve the data from the request, [hotspot=ngOnInitMethod]ngOnInit calls the [hotspot=thenClause]then() method on the Promise which takes in the data and stores it to the [hotspot=artistsClassMember]artists class member.
// ================================================================================================= // Creating the Angular component template // =================================================================================================
== Creating the Angular component template
Now that you have a service to fetch the data and a component to store it in, you will create a template to specify how the data will be displayed on the page. When you visit the page in the browser, the component populates the template to display the artists data with formatting.
app.component.html file.src/main/frontend/src/app/app.component.htmlThe template contains a [hotspot=artistsDiv]div element that is enumerated by using the ngFor directive. The artist variable is bound to the artists member of the component. The [hotspot=artistsDiv]div element itself and all elements contained within it are repeated for each artist, and the [hotspot=artistNameAndAlbumsLengthPlaceholders]{{ artist.name }} and [hotspot=artistNameAndAlbumsLengthPlaceholders]{{ artist.albums.length }} placeholders are populated with the information from each artist. The same strategy is used to display each [hotspot=albumDiv]album by each artist.
// ================================================================================================= // Building the front end // =================================================================================================
== Building the front end
The Open Liberty instance is already started, and the REST service is running. In a new command-line session, build the front end by running the following command in the start directory:
// Static guide instruction ifndef::cloud-hosted[] [role='command']
mvn generate-resourcesendif::[] // Cloud hosted guide instruction ifdef::cloud-hosted[]
cd /home/project/guide-rest-client-angular/start
mvn generate-resourcesendif::[]
The build might take a few minutes to complete. You can rebuild the front end at any time with the generate-resources Maven goal. Any local changes to your TypeScript or HTML are picked up when you build the front end.
// Static guide instruction ifndef::cloud-hosted[] Point your browser to the http://localhost:9080/app[http://localhost:9080/app^] web application root to see the following output: endif::[]
// Cloud hosted guide instruction ifdef::cloud-hosted[] Click the following button to visit the web application /app root endpoint: ::startApplication{port="9080" display="external" name="Visit application" route="/app"}
You will see the following output: endif::[]
If you use the curl command to access the web application root URL, you see only the application root page in HTML. The Angular framework uses JavaScript to render the HTML to display the application data. A web browser runs JavaScript, and the curl command doesn't.
== Testing the Angular client
No explicit code directly uses the consumed artist JSON, so you don't need to write any test cases.
// Static guide instruction ifndef::cloud-hosted[] Whenever you change and build your Angular implementation, the application root at http://localhost:9080/app[http://localhost:9080/app^] reflects the changes automatically. endif::[]
// Cloud hosted guide instruction ifdef::cloud-hosted[] Whenever you change and build your Angular implementation, the changes are automatically reflected at the URL for the launched application. endif::[]
When you are done checking the application root, exit dev mode by pressing CTRL+C in the command-line session where you ran the Liberty.
Although the Angular application that this guide shows you how to build is simple, when you build more complex Angular applications, testing becomes a crucial part of your development lifecycle. If you need to write test cases, follow the official unit testing and end-to-end testing documentation on the https://angular.io/guide/testing[official Angular page^].
== Great work! You're done!
You just accessed a simple RESTful web service and consumed its resources by using Angular in Open Liberty.
include::{common-includes}/attribution.adoc[subs="attributes"]