API Standards

Request Parameters

Jargon’s API expects parameters as either standard POST parameters, or as JSON in the body.

When using json in the body, the request should be accompanied by a ‘Content-Type: application/json’ header.

Response Format

Responses will be returned in JSON.

API Errors

Authorization Errors

Authorization errors will be returned as an Status 401 Unauthorized in the following cases:

  • No OAuth Token is provided
  • An expired OAuth token is provided
  • An OAuth token with the wrong scopes is provided

Validation Errors

Validation errors will be returned as an object with a list of validation errors in plain language.

HTTP 422 Unprocessable Entity { "localizations": [ "Name has already been taken" ] }

Not Found

Attempts to access non-existent content will return Status 404 Not Found

GET /api/localizations Localizations Index

Returns a collection of all Localizations

Request

  • The headers must include a valid authentication token with a public scope.

GET /api/localizations

Response

Returns a collection of all Localizations.

Status: 200 OK { "localizations": [ { "id": 23, "name": "Localization 1", "created_at": "2014-11-12T19:10:21.783Z", "updated_at": "2014-11-12T19:10:21.783Z", "available_locales": [ "Locale 1", "Locale 2" ], "locales": [ { "id": 42, "name": "Locale 1", "data": { "hello": "world" } }, { "id": 43, "name": "Locale 2", "data": { "hello": "no one" } } ] }, { "id": 24, "name": "Localization 2", "created_at": "2014-11-12T19:10:48.557Z", "updated_at": "2014-11-12T19:10:48.557Z", "available_locales": [ "Locale 1", "Locale 2" ], "locales": [ { "id": 44, "name": "Locale 1", "data": { "hello": "world" } }, { "id": 45, "name": "Locale 2", "data": { "hello": "mom" } } ] } ] }

POST /api/localizations Create Localization

Create a new localization.

Request

  • The headers must include a valid authentication token with a public scope.
  • Parameter name is required.

POST /api/localizations

{ "localization" : { "name": "Localization 3" } }

Response

Redirects to the new token on success, or returns validation errors on failure.

Status: 200 OK { "localization": { "id": 26, "name": "Localization 3", "created_at": "2014-11-12T19:29:57.829Z", "updated_at": "2014-11-12T19:29:57.829Z", "available_locales": [], "locales": [] } }

DELETE /api/localizations/:id Delete Localization

Deletes a localization, removing it from the database.

Request

  • The headers must include a valid authentication token with a public scope.
  • :id is the Localization ID

DELETE /api/localizations/26

Response

Redirects to the localization index on success

Status: 301 See Other { "localizations": [ { "id": 23, "name": "Localization 1", "created_at": "2014-11-12T19:10:21.783Z", "updated_at": "2014-11-12T19:10:21.783Z", "available_locales": [ "Locale 1", "Locale 2" ], "locales": [ { "id": 42, "name": "Locale 1", "data": { "hello": "world" } }, { "id": 43, "name": "Locale 2", "data": { "hello": "no one" } } ] }, { "id": 24, "name": "Localization 2", "created_at": "2014-11-12T19:10:48.557Z", "updated_at": "2014-11-12T19:10:48.557Z", "available_locales": [ "Locale 1", "Locale 2" ], "locales": [ { "id": 44, "name": "Locale 1", "data": { "hello": "world" } }, { "id": 45, "name": "Locale 2", "data": { "hello": "mom" } } ] } ] }

GET /api/localizations/:id Show Localization

Returns a representation of a localization.

Request

  • The headers must include a valid authentication token with a public scope.
  • :id is the Localization ID

GET /api/localizations/24

Response

Returns the localization.

Status: 200 OK { "localization": { "id": 24, "name": "Localization 2", "created_at": "2014-11-12T19:10:48.557Z", "updated_at": "2014-11-12T19:10:48.557Z", "available_locales": [ "Locale 1", "Locale 2" ], "locales": [ { "id": 44, "name": "Locale 1", "data": { "hello": "world" } }, { "id": 45, "name": "Locale 2", "data": { "hello": "mom" } } ] } }

PUT /api/localizations/:id Update Localization

Updates a localization, allowing you to change its name.

Request

  • The headers must include a valid authentication token with a public scope.
  • :id is the Localization ID

The only parameter that can be edited is name. Others are auto-generated and read-only.

PUT /api/localizations/24

{ "localization" : { "name": "Localization 2 Renamed" } }

Response

Redirects to the updated localization on success. Returns validation errors on failure.

Status: 301 See Other { "localization": { "id": 24, "name": "Localization 2 Renamed", "created_at": "2014-11-12T19:10:48.557Z", "updated_at": "2014-11-12T19:28:08.071Z", "available_locales": [ "Locale 1", "Locale 2" ], "locales": [ { "id": 44, "name": "Locale 1", "data": { "hello": "world" } }, { "id": 45, "name": "Locale 2", "data": { "hello": "mom" } } ] } }

GET /api/localizations/:id/locales Locales Index

Returns a list of all Locales for a given Localization.

Request

  • The headers must include a valid authentication token with a public scope.
  • :id is the Localization ID

GET /api/localizations/24/locales

Response

Returns a list of all Locales for a given Localization.

Status: 200 OK { "locales": [ "Locale 1", "Locale 2" ] }

POST /api/localizations/:id/locales Create Locale

Create a new Locale for a given Localization.

Request

  • The headers must include a valid authentication token with a write scope.
  • :id is the Localization ID
  • Parameter name is required.
  • Parameter json is a json representation of the Locale.

{ "locale" : { "name": "Locale 3", "json": { "hello": "world" } } }

Response

Redirects to the new token on success, or returns validation errors on failure.

Status: 200 OK { "locales": [ "Locale 1", "Locale 2", "Locale 3", "Locale 4", "Locale 5", "Locale 6" ] }

DELETE /api/localizations/:id/:locale Delete Locale

Deletes a localization, removing it from the database.

Request

  • The headers must include a valid authentication token with a write scope.
  • :id is the Localization ID
  • :locale is the Locale’s name.

DELETE /api/localizations/24/Locale 6

Response

Redirects to the locale index on success

Status: 200 OK { "locales": [ "Locale 1", "Locale 2", "Locale 3", "Locale 4", "Locale 5" ] }

GET /api/localizations/:id/:locale Locales Index

Returns a representation of a localization.

Request

  • The headers must include a valid authentication token with a public scope.
  • :id is the Localization ID
  • :locale is the Locale’s name

GET /api/localizations/24/Locale 6

Response

Returns the Locale.

Status: 200 OK { "locale": { "id": 44, "name": "Locale 1", "data": { "hello": "world" } } }

PUT /api/localizations/:id/:locale Update Locale

Updates a Locale.

Request

  • The headers must include a valid authentication token with a write scope.
  • :id is the Localization ID
  • :locale is the Locale’s name.

PUT /api/localizations/24/Locale 6

{ "locale" : { "name": "Locale 6", "json": { "hello": "mom" } } }

Response

Redirects to the updated localization on success. Returns validation errors on failure.

Status: 200 OK { "locale": { "id": 49, "name": "Locale 6", "data": { "hello": "mom" } } }

GET /api/uuid/:uuid/:locale Locale by UUID

Returns a representation of a localization.

Request

  • :uuid is the Localization’s UUID
  • :locale is the Locale’s name

GET /api/uuid/61267710-4286-4db9-a074-3dd5ae9993c1/Locale 1

Response

Returns the Locale.

Status: 200 OK { "locale": { "id": 42, "name": "Locale 1", "data": { "hello": "world" } } }

GET /api/uuid/:uuid Localization by UUID

Returns a representation of a localization.

Request

  • :uuid is the Localization’s UUID

GET /api/uuid/61267710-4286-4db9-a074-3dd5ae9993c1

Response

Returns the Locale.

Status: 200 OK { "localization": { "id": 23, "name": "Localization 1", "created_at": "2014-11-12T19:10:21.783Z", "updated_at": "2014-11-12T19:10:21.783Z", "available_locales": [ "Locale 1", "Locale 2" ], "locales": [ { "id": 42, "name": "Locale 1", "data": { "hello": "world" } }, { "id": 43, "name": "Locale 2", "data": { "hello": "no one" } } ] } }