Getting Started With SKL
As mentioned in the Introduction, SKL (Standard Knowledge Language) can be used with Standard SDK to make it easier to interact with multiple similar APIs. Instead of writing custom code for the non-standard data formats of each API you want to integrate with, SKL enables you to use abstractions to build over a common model.
If you haven't already, review the Conceptual Example of why and how a developer uses SKL.
Install
To get started with Standard SDK and SKL in Node.js, install the module with npm or yarn:
or
To use Standard SDK in a browser, you'll need to use a bundling tool such as Webpack, Rollup, Parcel, or Browserify. Some bundlers may require a bit of configuration, such as setting browser: true
in rollup-plugin-resolve.
Walkthrough
Lets assume we're building an events calendar web-app for the city we live in. On this calendar app, we want to display events listed on major public event ticketing platforms like Ticketmaster, Stubhub, & Seatgeek, etc. SKL is perfect for this task. With just a few Schemas, it dramatically reduces the amount code we would have to write to ingest event data from multiple APIs.
I order to build our system we have to:
Define SKL Schemas to abstract the data and operations we will be accessing from each API into a common data model.
Use a Standard Knowledge Language Engine (SKL Engine) to read and execute our Schemas to perform the operations our app requires.
Write code to implement the application
1. Define SKL Schemas
As stated in the SKL documentation:
SKL is a schema validated and configuration driven framework. Standard Knowledge Schemas serve both as schema to ensure data conforms to specific structures, and configuration detailing what capabilities are possible and how those capabilities are performed. Schemas are made up of Nouns, Verbs, and Mappings:
Data is translated through Nouns.
Capabilities are represented by Verbs.
Mappings are used to relate Nouns and Verbs and translate between raw data and capabilities and Nouns and Verbs
In order to use SKL for our application, we need to create Schemas representing:
An abstraction of Events which data from each event ticketing platform will be mapped to. This is our primary Noun. In this example, we use the Event data type from schema.org.
An abstraction of the operation we want to perform with the API of each event ticketing platform. We want to get a list of events from each platform, filtered by only those in our city. We'll call this
getEvents
, it is a Verb.Rules defining how our Verb
getEvents
and its standardized parameters get mapped to the correct operation of each API and how the unique response of each API gets mapped into the standardized return value of the Verb. These are Mappings.
Examples of these Schemas are available as JSON-LD in the unified-events-api/skl-schemas folder of the SKL Examples repository. There you'll see the Event Noun in the nouns.json file, the getEvents
Verb in the verbs.json file, the mappings in the mappings.json file, and entities needed for SKL to work in entities.json
API Security Credentials
Most APIs require a sensitive access token or API key to make authenticated requests. SKL automatically reads these from a Security Credentials
entity in your schemas. You can see an example of one in entities.json. You'll notice that the apiKey
field is stubbed out with ENV_TICKETMASTER_APIKEY
. This is because we don't want to put a real API key in the public repository on Github. When the example code is run, we swap out any string starting with the prefix ENV_
with the value of the environment variable named the remainder of the stub, in this case TICKETMASTER_APIKEY
. If your schemas are private, you can include the environment variables directly in the Schemas.
2. Use a SKL Engine
Now that we have schemas, we need to use an SKL Engine to read and execute them according to our code. Standard SDK JS includes the SKL JS Engine inside of it. This way, with only one dependency, you can use Standard SDK normally when creating abstractions is too hard for your circumstance or use case but have the power of SKL's abstractions to solve the majority of your needs.
Build Standard SDK using the sklEngineOptions
argument. This argument is the same interface as the arguments to build SKL JS Engine.
In Typescript:
If your schemas are separated across multiple files and/or use a JSON-LD @context
, you should combine and frame them using a function like combineSchemas
in the SKL Examples repository.
3. Write Code
Finally, you're ready to write some code using the Standard SDK instance you just built. Since we provided sklEngineOptions
you can access the SKL JS Engine through standardSdk.skl
.
In Typescript:
This code will tell the SKL JS Engine to execute the getEvents
Verb using each account
represented by URIs (eg. https://example.com/data/TicketmasterAccount
). In entities.json, which you copied or reviewed earlier, there are Schemas which contain the OpenAPI specifications and security credentials for each API. In mappings.json, there are mappings which relate each Integration with the getEvents Verb. Together, these entities and mappings inform the SKL JS Engine how to map the parameters of the getEvents
Verb to the parameters of each API, send a properly formatted web request to the API, and map the response of the API into our standardized Event Noun.
Last updated