API Reference

The Jahuty API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Currently, we only support a single environment.

All requests use the current version of our API. When we make backwards-incompatible changes to the API, which we do our best to avoid, we'll release a new major version and introduce a versioning scheme.

Base URL
https://www.jahuty.com/api
SDKs

Authentication

The Jahuty API uses API keys to authenticate requests. You can view and manage your organization's API keys in its dashboard.

There are two types of API keys: public and secret. Although public keys are not secret and carry limited priviledges, you should not share them in publicly accessible areas such as Github, Bitbucket, client-side code, and so forth.

Each SDK provides a method to set your organization's API key using a static method or public static variable. Once it's set, it'll be included in subsequent requests automatically.

If you're using the API directly, you can pass your organization's API token via bearer authentication, by setting the Authorization to request header's value to Bearer YOUR_API_KEY.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

To learn more about API keys, see managing API keys.

Authenticated request
curl https://www.jahuty.com/api/snippets/1 -H \
  "Authorization: Bearer kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"; \
  echo
Your API key

A sample test API key is included in all the examples here, so you can test any example right away:

kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc

To test requests using your account, replace the sample API key with one of your organization's actual API keys.

Errors

Jahuty uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: codes in the 2xx range indicate success; codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, the resource does not exist, etc.); and, codes in the 5xx range indicate an error with Jahuty's servers (these are rare).

When an error does occur, the Jahuty API will respond with the application/problem+json content type.

HTTP status codes
200 - OK
Everything worked as expected.
401 - Unauthorized
No valid API key provided.
402 - Payment Required
Your free trial or subscription has expired.
403 - Forbidden
The API key doesn't have permissions to perform the request.
404 - Not Found
The requested resource doesn't exist.
500, 502, 503, 504 - Server Errors
Something went wrong on Jahuty's end. (These are rare.)

Attributes

Jahuty uses the application/problem+json resource to describe errors.

status integer
The original HTTP status code.
title string
A short, human-readable title for the general error type.
detail string
A human-readable description of the specific error.
type string
A URL to more information about the reported error.
Error object
{
  "status": 404,
  "title": "Not found",
  "detail": "The requested resource was not found",
  "type": "https://en.wikipedia.org/wiki/List_of_HTTP_status_codes"
}

Handling errors

Our SDKs raise exceptions for errors that need your attention such as invalid parameters or authentication errors.

We don't recommend writing code that handles API exceptions. An exception will likely only occur in a situation which requires your attention.

Handling exceptions
use Jahuty\Jahuty\Jahuty;
use Jahuty\Jahuty\Snippet;
use Jahuty\Jahuty\Exception\NotOk;

Jahuty::setKey('kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc');

try {
  // Returns 404 (raising exception) because snippet and key do not match.
  Snippet::get(999);
} catch (NotOk $e) {
  $p = $e->getProblem();

  echo $p->getStatus();
  echo $p->getType();
  echo $p->getDetail();
}
require "jahuty"

Jahuty.key = "kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"

begin
  # Responds 404 (raising exception) because snippet and key do not match.
  Snippet.get 999
rescue Jahuty::Exception::NotOk => e
  p = e.problem

  puts p.status
  puts p.type
  puts p.detail
end

Snippets

A snippet is a string you manage through our website; fetch using our SDKs or API; and, display in your application on-demand. Each snippet is assigned a unique identifier (aka, id) that you'll use to refer to it.

Endpoints
GET /snippets/:id

Attributes

id id
A unique identifier for the snippet.
name string
A human-readable name for the snippet.
content string
The snippet's HTML content.
Snippet object
{
  "id": 1,
  "content": "This is my first snippet!"
}

Retrieve a snippet

Retrieves the details of an existing snippet. You need only supply the unique identifier that was assigned to the snippet upon creation.

Arguments

id integer
The identifier of the snippet to retrieve.
params hash optional
A URL-encoded, JSON string of variables to pass into the snippet.

Returns

Returns a snippet object. When requesting a snippet that does not exist or you are not authorized to access, a 404 error will be returned.

GET snippets/:id
curl https://www.jahuty.com/api/snippets/1 -H "Authorization: Bearer kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"; echo
use Jahuty\Jahuty\Jahuty;

Jahuty::setKey('kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc');

echo Snippet::get(1);
require "Jahuty"

Jahuty.key = "kn2Kj5ijmT2pH6ZKqAQyNexUqKeRM4VG6DDgWN1lIcc"

puts Jahuty::Snippet.get 1
Response
{
  "id": 1,
  "name": "This is my first snippet!"
}

Need help?

We're happy to answer any questions you may have.

Ask a question