@byu-oit-sdk/client v0.7.1

@byu-oit-sdk/client

The main components underlying the BYU SDK are clients, commands, and middleware. Understanding each is crucial for troubleshooting problems, creating new SDKs, or extending an existing SDK.

Note that the @byu-oit-sdk/client package specifically isn't designed to be used in applications alone. Rather, it is a base class and shared-code repository that other clients can extend and use for full, app-ready functionality.

If your app needs to make a variety of BYU API calls, the BYU Client is probably what you need. If you just need to make API calls to one specific API, there may be a specific client that would be more simple to use. See a list of domain-specific clients here.

Requirements:

• Node.js 18+
  • or Node.js 10+ with fetch and crypto polyfills
• npm v9+

Client

Simply put, the client is the actuator of a request. Every client has a send function which serializes requests and deserializes responses. A client represents a set of commonly grouped endpoints. These endpoints usually share the same base path or are hosted by the same web server.

For a usage example, see below.

Command

Commands represent a single HTTP request. The input of a command is an object that should include all the necessary parameters that a user might want to specify to customize the HTTP response. The output of a command is a deserialized representation of the raw HTTP response, usually taking the form of a class instance or an object whose shape is well-defined. When a non-2xx response code is received, an error is thrown. Response errors should extend the built-in HttpResponseError.

Using commands abstracts the complexity of formatting HTTP requests, and validating responses away from developers.

Middleware

The Middleware facilitates the stages of the middleware stack. To learn more about the middleware stack, read Introducing Middleware Stack in Modular AWS SDK for JavaScript.

Usage

Note This example uses the Persons Client.

const client = new PersonsClient()
const request = new GetPersonBasicCommand({byuId: '000000000'})
const data = await client.send(request)
// Do something with the data
console.info(`Found BYU ID ${data.byuId}`)

Creating Clients

New clients may be added under the /clients directory. Clients should extend this package by adding serializer and deserializer middleware to the middleware stack along with other additional middleware. A client must export a Client class and every Command class that the client supports.

Client Nomenclature & Versioning

If I was writing an SDK for a persons API, I would name the package @byu-oit-sdk/client-persons. The class would then be called, PersonsClient. The major version of the package should follow the major version of the API (e.g. @byu-oit-sdk/client-persons@3 should be used for the Persons v3 API).

Recommended Middleware

Most clients will implement the @byu-oit-sdk/middleware-retry and @byu-oit-sdk/middleware-token packages, but it is not required. Please refer to their documentation for how to do so.

HttpResponseError

Any HTTP Error should be thrown by the client. It is not acceptable to return the error because the Input and Output types are deserialized and simplified forms of the fetch Request and Response. It saves the developer the hassle of serializing, parsing, and type checking/narrowing when we only return one type and throw non-2xx responses.

Exceptional Error Cases

Sometimes, it may be completely acceptable to receive a 404 response in a particular application. In that case, the client should define a NotFoundError which the developer may choose to swallow handle by returning null. Then the output would contain either Output | null as shown in the example below.

const response = client.send(command).catch(e => {
    if (e instanceof NotFoundError) return null
    throw e // or handle other errors
})

const response = client.send(command).catch(e => {
    if (e instanceof NotFoundError) return null
    throw e // or handle other errors
})