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 production environment, because content doesn't need separate environments.

All requests use the current version of our API. When we make backwards-incompatible changes to the API, 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 API keys in your 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 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 API token via bearer auth, by seeting the Authorization 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 managing API keys, see dashboard.

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

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

78e202009659616eceed79c01a75bfe9

To test requests using your account, replace the sample API key with your actual API key.

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.). 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 an exceptional situation which requires your attention.

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

try {
  // use Jahuty's code here...
} catch (NotOk $e) {
  // any status code but 200
  $p = $e->getProblem();

  echo $p->getStatus();
  echo $p->getType();
  echo $p->getDetail();
}
begin
  # use Jahuty's code here...
rescue Jahuty::Snippet::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 hash of numeric, string, or array parameters to pass into your 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 78e202009659616eceed79c01a75bfe9"; echo
use Jahuty\Snippet\Snippet;

Snippet::key('78e202009659616eceed79c01a75bfe9');

echo Snippet::get(1);
Jahuty::Snippet.key = "78e202009659616eceed79c01a75bfe9"

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

That's it!

Questions or suggestions? Let us know.

Questions?

We're happy to help.

Contact us