swsh Public API Documentation

0.0.5

Introduction

The swsh Public API can be used to create, manage, and access resources on the swsh platform. The API acts as an extension of the swsh account the API key was created for. Therefore, all resources will be owned by that account. Because the API key is linked to a user account, all resources can be managed and accessed using the website and app clients as normal. If there's functionality missing from the API, you can use the website or app clients to manage resources manually.

This API is designed for simplicity in user and developer experience. The goal is to allow end-users to interact with swsh without needing to create credentials or link their account. For the developer, we aim for a simple implementation process with minimal overhead. In the inspiration section, you can read about some potential integration examples that demonstrate these design philosophies.

Getting Started

1. Create an email-linked account to represent your product or organization (you may need to log out of your personal account before creating a new one)
2. Generate an API key and store it securely in your backend secret manager
3. (Optional) Install the TypeScript client (npm install @somewhere-somehow/swsh-public-api)
4. Start making requests to the API!

Inspiration

Calendar Integration

Imagine you're building a product that helps you and your friends find a time to meet which creates a calendar event for that decided time. The user clicks on a button in your app that creates an event and automatically invites their selected friends using a third party calendar. You can use the swsh API to automatically create an album for the event which is linked in the calendar event description. Everyone invited to the event can simply click on the swsh link, create an account, and upload/view the photos for that event.

As a developer, integration would be very simple. To get set up, follow the getting started steps for creating an account and API key. In your event creation endpoint, you would call the /album/createAlbum endpoint to create an album with the same name as the event. Then, when invoking the third party calendar API, you can include the shareUrl in the description.

Event Ticketing Platform

Imagine you're building a platform that allows users to create and sell tickets for events. You can use the swsh API to create an album for each event to allow users to upload and view photos for that event. When a user buys a ticket, you can include the shareUrl in the ticket email. This way, the user can view photos of the event after it's over. If your event has a professional photographer, they can upload the photos to the generated swsh album for users to view and download. If there's a page where they can view their tickets, you can include the shareUrl there as well.

To integrate this into your product, follow the getting started steps for creating an account and API key. On your event creation endpoint, you would call the /album/createAlbum endpoint to create an album with the same name as the event. You can store the shareUrl on the event object for later use. When a user buys a ticket, you can include the cached shareUrl in the ticket email. If you have a page where users can view their tickets, you can present the cached shareUrl there as well.

Client

For your convenience, we have an auto-generated TypeScript library you can use to interact with the API. Functions map directly to their corresponding API route, unless otherwise noted. The TypeScript SDK only supports ESM and is meant to be used in backend environments. Our client is generated using Fern's SDK tools. You can install the SDK using your favorite package manager.

npm install @somewhere-somehow/swsh-public-api

import { SwshApiClient } from "swsh-public-api";

const client = new SwshApiClient({
    apiKey: "<YOUR_API_KEY>",
});
const { data } = await client.ping();

You can find the source code and report issues for the TypeScript client on GitHub. The npm package can be found here.

Authentication

Authentication is handled using an API key. You can create an API key in the account settings page. The API key is used to authenticate all requests to the API. The API key should be kept secret and not shared with anyone. Do not send requests from frontend environments. If you believe your API key has been compromised, you can delete it in the developer settings section of the settings page.

All developer accounts must have a verified email address to create an API key. We strongly recommend against using your personal swsh account if you represent an organization. Instead, you can create a new account using an email address here. You may need to log out before creating a new account.

The API key is passed in the x-api-key header of each request. If you're using the TypeScript client, you can set the API key for the client during initialization in the apiKey field.

import { SwshApiClient } from "swsh-public-api";

const client = new SwshApiClient({
    apiKey: "<YOUR_API_KEY>",
});

Rate Limit

The API has a rate limit enforced on every request. This rate limit is subject to change at any point. You can view the rate limit using the x-rate-limit-consumed and x-rate-limit-remaining headers on every request. If you exceed the rate limit, you will receive a 429 Too Many Requests response. If you receive this response, you should wait until the rate limit resets before making more requests. Rate limits are specific to each account, so cycling API keys will not increase your limit. If you would like to have your rate limit increased, contact us. If you're using the TypeScript client, you may need to send a custom fetch request to access response headers.

const res = await fetch("https://public-api.joinswsh.com/ping", {
    headers: {
        "x-api-key": "<YOUR_API_KEY>",
    },
});
const numRemaining = Number(res.headers.get("x-rate-limit-remaining"));
const numConsumed = Number(res.headers.get("x-rate-limit-consumed"));
const periodEnd = Number(res.headers.get("x-rate-limit-period-end"));

Rate Limit Headers

• x-rate-limit-consumed: The number of requests consumed in the current rate limit window.
• x-rate-limit-remaining: The number of requests remaining in the current rate limit window.
• x-rate-limit-period-end: The time at which the current rate limit window ends in seconds since the Unix epoch.

Status

You can view the uptime status of our public API on our status page. We also offer a /ping endpoint to check if the API is online.

Feedback

If you have any questions, need help, or would like to request additional API functionality, you can contact us here. Also, you can just email me (hi, I'm Nathan!) at nathan (@) joinswsh.com. I'm happy to hop on call to walk you through implementation or help you with any issues you're facing.