Getting Started With SKL
Last updated
Last updated
As mentioned in the , SKL () 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 of why and how a developer uses SKL.
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.
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 to abstract the data and operations we will be accessing from each API into a common data model.
Use a to read and execute our Schemas to perform the operations our app requires.
Write code to implement the application
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:
In Typescript:
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:
As stated in the :
An abstraction of Events which data from each event ticketing platform will be mapped to. This is our primary . In this example, we use the Event data type from .
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 .
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 .
Examples of these Schemas are available as JSON-LD in the folder of the repository. There you'll see the Event Noun in the file, the getEvents
Verb in the file, the mappings in the file, and entities needed for SKL to work in
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 . 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.
Now that we have schemas, we need to use an to read and execute them according to our code. Standard SDK JS includes the 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 .
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 in the repository.
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 , which you copied or reviewed earlier, there are Schemas which contain the and for each API. In , there are mappings which relate each with the . 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.