This library provides components which provide easier usage of the GeoPlatform API. It is not required to interact with the GeoPlatform API, but offers services and helper functionality to speed up your application's integration with the GeoPlatform.
This library is framework flexible. The default implementations require Axios to facilitate AJAX XHR requests with the GeoPlatform API hosts. Alternatively, implementations for Angular 1.x, Angular 8+ and NodeJS are provided.
This library requires the following dependencies be present in your application:
For more information about how to use API Client inside AngularJS, see the AngularJS documentation.
For more information about how to use API Client inside Angular, see the Angular documentation
For more information about how to use API Client inside NodeJS, see the Node documentation
Include API Client as a dependency of your application inside the package.json file (or similar dependency definition file).
...
"dependencies": {
...,
"@geoplatform/client": "git+https://github.com/GeoPlatform/client-api.git",
...
}
...Then run npm install @geoplatform/client or yarn add @geoplatform/client.
Note: You can try installing using the --save option but NPM sometimes has issues with installing and updating GIT repo-hosted modules. It's better to explicitly add it to your package.json and then install it.
If not using a build tool like WebPack or Browserify, make sure to include the distribution in your application's HTML file(s):
<script src="https://github.com/GeoPlatform/client-api/raw/master/path/to/geoplatform.client.js"></script>Note: You can also load the library from a CDN:
<script src="https://s3.amazonaws.com/geoplatform-cdn/@geoplatform/client/_VERSION_/js/geoplatform.client.js"></script>//include the config export used to define API properties needed later
const ItemService = require('@geoplatform/client').ItemService;//include the config export used to define API properties needed later
import { ItemService } from '@geoplatform/client';//include the config export used to define API properties needed later
const ItemService = geoplatform.client.ItemService;The Config object exposed by GeoPlatform API Client allows configuration of
environment variables necessary to interact with the GeoPlatform API. Below is
an example of how to configure this object.
import { Config } from '@geoplatform/client';
Config.configure({
//REQUIRED: environment the application is deployed within
// one of "development", "sit", "stg", "prd", or "production"
"env" : "development",
//Optional, URL to GeoPlatform UAL for API usage. Override this only if you are
// communicating with a different instance of GeoPlatform API or if you are
// using a server-side proxy of API - see below for more info on this.
"ualUrl" : "https://ual.geoplatform.gov",
//timeout max for requests
"timeout" : "5000",
//application identifier of the application using the API
"appId" : "my-app"
});
let url = Config.ualUrl; //will now be set as configured aboveNote: You must configure this before importing other GeoPlatform libraries which use this library, such as GeoPlatform.MapCore.
To learn how to use the GeoPlatform API to fetch, create, update, and remove GeoPlatform Assets, see the GeoPlatform API and Query documentation.
If you are modifying data - which requires OAuth 2.0 identity tokens be supplied to the API Client http client instances - or are worried about cross-origin request security (CORS) issues, you should use server-side proxies of the API Client. The proxies are instances of the same API Client service instances used client-side but bound to HTTP endpoints through ExpressJS in NodeJS. The proxies allow better authorization token refresh handling and avoid browser limitations involving CORS.
To enable server-side proxies in the NodeJS portion of your application, check out the proxy documentation.
Check out the authentication documentation for details about how to enable authenticating users and providing authorization tokens with requests.
Look inside the "examples" folder and its sub-folders to see how to use the client API.
To run the NodeJS examples, run Node from the api project root folder passing it
the desired example JS file (e.g., node examples/node/item.js)
class MyClass { ... })let myObj = ...)const DEFINITIONS = { ... })Version 0.3 is built using TypeScript and ng-packagr. It uses the namespaced package name ("@geoplatform/client") instead of the previous "geoplatform.client" and separates the environment-specific support classes into sub-packages: "@geoplatform/client/node", "@geoplatform/client/angularjs", and the new "@geoplatform/client/angular".
The default XHR mechanism in 0.3 has been migrated from jQuery's AJAX to Axios to better work when used inside non-browser environments such as NodeJS and server-side Angular.
Update the module name in your package.json and install the necessary dependency libs (Q and Axios, plus any environment-specific libraries).
"dependencies": {
"@geoplatform/client": "git+https://github.com/GeoPlatform/client-api.git",
"axios": "0.18.0",
"q": "1.5.1"
}Use the update package name when include the appropriate library-specific sub-package as necessary:
<!--
Inside Single Page Application pages
-->
<!-- base library, uses Axios to do XHR requests -->
<script src="https://github.com/GeoPlatform/client-api/raw/master/node_modules/@geoplatform/client/dist/bundles/geoplatform-client.umd.min.js"></script>
<!-- angularJS support, uses $http to do XHR requests -->
<script src="https://github.com/GeoPlatform/client-api/raw/master/node_modules/@geoplatform/client/dist/bundles/geoplatform-client-angularjs.umd.min.js"></script>
<script>
let ItemService = geoplatform.client.ItemService;
let NGHttpClient = geoplatform.client.angularjs.NGHttpClient;
</script>/* Inside NodeJS */
const ItemService = require("@geoplatform/client").ItemService;
const NodeHttpClient = require("@geoplatform/client/node").NodeHttpClient;/* Inside Angular (ES6) */
import { ItemService } from "@geoplatform/client";
import { NG2HttpClient } from "@geoplatform/client/angular");Note: When using version 0.3 inside client-side SPAs that do not support ES6 imports, the global constant ("GeoPlatformClient") has been replaced with "geoplatform.client" (case sensitive). Sub-package constants extend this constant (e.g., "geoplatform.client.angularjs" for AngularJS-specific classes, "geoplatform.client.angular" for Angular).
Use "target" : "es6" as using older compilation targets may generate errors
regarding things such as superclass constructor calls.