Repository Endpoints

The repository endpoints are used to view and manage the repositories that have been ingested into the service. They respond and deal with one of the following entities:

Entities

Repository Entity

Repository entities represent repositories that have been ingested into the service. As JSON they look like this:

{
	// A unique identifier for the repo
	"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

	// The name of the repo on GitHub
	"name": "repo-name",

	// The GitHub URL for the repo
	"url": "https://github.com/Financial-Times/repo-name",

	// The repo type, as outlined in the Origami Spec
	"type": "module",

	// The repo category, as outlined in the Origami Spec (under origamiCategory).
	// Set to `null` when the repo type is not `module`
	"subType": "component",

	// The latest version of the repo
	"version": "1.1.0",

	// The latest exact git tag of the repo
	"versionTag": "v1.1.0",

	// The custom scheme of the imageset, if the repo represents an imageset
	"imageSetScheme": "ftexample-v1",

	// A description and keywords for the repo, based on one of the JSON manifests in it
	"description": "An example Node.js module",
	"keywords": [
		"node",
		"example"
	],

	// Keywords inferred from the repo description and component demos (excludes explicitly-defined keywords). This property should be considered experimental.
	"inferredKeywords": [
		"module"
	],

	// A list of brands that this repo supports if it is a component.
	// If it does not explicitly support brands, it will be an empty Array.
	// If it is not a component, the value will be `null`
	"brands": [
		"master",
		"internal"
	],

	// A list of languages that this repo exports (based on manifest file "main" properties)
	"keywords": [
		"js",
		"scss"
	],

	// Support information for the repo
	"support": {
		"email": "origami.support@ft.com",
		"channel": "#ft-origami",

		// An easy way to determine whether the Origami team maintains this repo
		"isOrigami": true,

		// Whether the latest version of the repo is a prerelease
		// (alpha, beta, or release-candidate)
		"isPrerelease": false
	},

	// The paths for other API resources related to this repository.
	// Each key will be either a string path or `null` if the resource does not exists
	"resources": {
		"self": "...",         // The canonical endpoint for this repository
		"versions": "...",     // The endpoint which lists all versions for this repository
		"manifests": {         // The endpoints which output named manifest files
			"origami": "..."   // (other manifest files appear as key/value pairs)
		},
		"markdown": {          // The endpoints which output named markdown files
			"readme": "..."    // (other manifest files appear as key/value pairs)
		},
		"demos": "...",        // The endpoint which lists all demos for this repository
		"images": "...",       // The endpoint which lists all images for this repository
		"dependencies": "..."  // The endpoint which lists all dependencies for this repository
	},

	// Additional supporting URLs for this repository. Each key will be either a
	// string URL or `null` if that supporting URL is not defined or does not apply
	"supportingUrls": {
		"ci": "...",      // A continuous integration dashboard for this repository
		"issues": "...",  // The GitHub issues URL for this repository
		"service": "..."  // The primary URL for the service, if this repository type is "service"
	},

	// When the repo was last ingested by 
	"lastIngested": "2017-11-06T09:56:45.991Z"
}

Version Entity

Version entities represent individual versions or releases of repositories that have been ingested into the service. As JSON they look like very similar to Repository entities, but with the following differences:

{
	// A unique identifier for the version, rather than the repo
	"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

	// A unique identifier for the repo this version belongs to
	"repo": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

	// The semver version number that corresponds to this release
	"version": "1.1.0",

	// The latest exact git tag of the version
	"version": "v1.1.0",

	// The paths for other API resources related to this version
	"resources": {
		"self": "...",  // The canonical endpoint for this version
		"repo": "...",  // The canonical endpoint for the repository this version belongs to
		// The rest of these are the same as the resources for Repository entities
	}
}

Demo Entity

Demo entities represent individual Origami demos for a Version. They differ from accessing the origami.json manifest demos in that they are sanitized and normalised. As JSON they look like this:

{
	// The identifier for the demo (normally the file name)
	"id": "example",

	// The title of the demo
	"title": "Example Demo",

	// A short description of the demo, or `null` if one is not given
	"description": "This is an example demo",

	// Additional supporting URLs for this demo. Each key will be either a
	// string URL or `null` if that supporting URL is not defined or does not apply
	"supportingUrls": {
		"live": "...",  // A live rendered version of this demo as an HTML page
		"html": "..."   // The HTML code required to reproduce this demo, with no boilerplate included
	},

	// Flags indicating which parts of the demo should be displayed
	"display": {
		"live": true,  // Whether the live demo should be considered useful and displayable
		"html": true   // Whether the demo HTML should be considered useful and displayable
	}
}

Image Entity

Image entities represent individual images in an Origami image set. They differ from accessing the imageset.json manifest images in that they are sanitized and normalised. As JSON they look like this:

{
	// The title of the image
	"title": "example-image",

	// Additional supporting URLs for this image. Each key will be a string image URL
	"supportingUrls": {
		"full": "...",  // An Image Service URL pointing to the full size image
		"w200": "..."   // An Image Service URL pointing to a 200px wide copy of the image
	}
}

Dependency Entity

Dependency entities represent individual dependencies that an Origami repository has. As JSON they look like this:

{
	// The name of the dependency
	"name": "example-dependency",

	// The allowed Semver range for the dependency
	"version": "^1.2.3",

	// The registry that the dependency can be found in (either "bower" or "npm")
	"source": "bower",

	// Whether the dependency is a development dependency
	"isDev": false,

	// Whether the dependency is optional (npm only)
	"isOptional": false
}

Get all repositories

Get a list of all available Origami repositories as an array, with optional filtering. This endpoint responds with an array of Repository entities. This endpoint requires the READ permission.

Request

Method GET
Path /v1/repos
Querystring
brand
Specify a brand (or a comma-delimited list of brands) to filter repositories by. Possible values are: master, internal, whitelabel. Any repository which doesn't include this brand will not be output. If this parameter is set to none, null, or undefined then only repositories which are not branded will be output. If this parameter is set to all then only repositories which have at least one brand will be output.
q
Specify text to search repositories by. Searchable fields are name, description, keywords, and demo titles. Any repository which doesn't match the search string will not be output.
status
Specify an Origami component support status (or a comma-delimited list of statuses) to filter repositories by. Possible values are: active, maintained, experimental, deprecated, dead. Any repository which doesn't have this status will not be output.
type
Specify an Origami repo type (or a comma-delimited list of types) to filter repositories by. Possible values are: module, service, imageset. Any repository which doesn't have this type will not be output.
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
Headers
Content-Type
application/json on success
text/html on error
Body Array of Repository entities

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos

Get a repository

Get a single Origami repository by ID. This endpoint responds with a Repository entity. This endpoint requires the READ permission.

Request

Method GET
Path
(aliases)
/v1/repos/:repo-id
(where :repo-id is the unique identifier for a Repository)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if a repo matching :repo-id does not exist
Headers
Content-Type
application/json on success
text/html on error
Body Repository entity

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX

Aliases

The following aliases exist for this endpoint, and each will respond with a 307 status and a Location header pointing to the correct endpoint. When redirecting, a client should forward on any authentication headers.

Get all versions for a repository

Get a list of all versions for an Origami repository as an array. This endpoint responds with an array of Version entities. This endpoint requires the READ permission.

Request

Method GET
Path /v1/repos/:repo-id/versions
(where :repo-id is the unique identifier for a Repository)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if a repo matching :repo-id does not exist
Headers
Content-Type
application/json on success
text/html on error
Body Array of Version entities

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX/versions

Get a repository version

Get a single version for an Origami repository by ID. This endpoint responds with a Version entity. This endpoint requires the READ permission.

Request

Method GET
Path
(aliases)
/v1/repos/:repo-id/versions/:version-id
(where :repo-id is the unique identifier for a Repository and :version-id is the unique identifier for a Version of it)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if a repo and version matching :repo-id and :version-id does not exist
Headers
Content-Type
application/json on success
text/html on error
Body Version entity

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX/versions/XXXXXX

Aliases

The following aliases exist for this endpoint, and each will respond with a 307 status and a Location header pointing to the correct endpoint. When redirecting, a client should forward on any authentication headers.

Get a raw manifest file

Get a single manifest for an Origami repository and version by type. This endpoint responds with the JSON contents of the requested manifest file. This endpoint requires the READ permission.

Request

Method GET
Path /v1/repos/:repo-id/versions/:version-id/manifests/:manifest-type
(where :repo-id is the unique identifier for a Repository, :version-id is the unique identifier for a Version of it, and :manifest-type is the type of manifest to retrieve – one of about, bower, imageset, origami, or package. The only manifest type that is guaranteed to exist is origami)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if a manifest matching :repo-id, :version-id, and :manifest-type does not exist
Headers
Content-Type
application/json on success
text/html on error
Body Manifest contents

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX/versions/XXXXXX/manifests/origami

Get a raw markdown document

Get a single markdown document for an Origami repository and version by type. This endpoint responds with the markdown contents of the requested document. This endpoint requires the READ permission.

Request

Method GET
Path /v1/repos/:repo-id/versions/:version-id/markdown/:markdown-type
(where :repo-id is the unique identifier for a Repository, :version-id is the unique identifier for a Version of it, and :markdown-type is the name of the document to retrieve – one of designguidelines or readme)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if a markdown document matching :repo-id, :version-id, and :markdown-type does not exist
Headers
Content-Type
text/markdown on success
text/html on error
Body Markdown contents

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX/versions/XXXXXX/markdown/readme

Get demos for a version

Get a list of all demos for an Origami repository and version. This endpoint responds with an array of Demo entities. This endpoint requires the READ permission.

Request

Method GET
Path /v1/repos/:repo-id/versions/:version-id/demos
(where :repo-id is the unique identifier for a Repository and :version-id is the unique identifier for a Version of it)
Querystring
brand
Used to filter out any demos which shouldn't be displayed for the given brand. Demos with a brand configuration that doesn't include this brand will not be output.
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if there are no non-hidden demos for the :repo-id and :version-id
Headers
Content-Type
application/json on success
text/html on error
Body Array of Demo entities

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX/versions/XXXXXX/demos

Get images for a version

Get a list of all images for an Origami repository and version, assuming that the repository is an image set. This endpoint responds with an array of Image entities. This endpoint requires the READ permission.

Request

Method GET
Path /v1/repos/:repo-id/versions/:version-id/images
(where :repo-id is the unique identifier for a Repository and :version-id is the unique identifier for a Version of it)
Querystring
sourceParam
Used to set the source querystring parameter for returned image URLs
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if there are no images for the :repo-id and :version-id, or the repository is not an image set
Headers
Content-Type
application/json on success
text/html on error
Body Array of Image entities

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX/versions/XXXXXX/images?sourceParam=curl

Get dependencies for a version

Get a list of all dependencies for an Origami repository and version. This endpoint responds with an array of Dependency entities. This endpoint requires the READ permission.

Request

Method GET
Path /v1/repos/:repo-id/versions/:version-id/dependencies
(where :repo-id is the unique identifier for a Repository and :version-id is the unique identifier for a Version of it)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if there are no dependencies for the :repo-id and :version-id
Headers
Content-Type
application/json on success
text/html on error
Body Array of Dependency entities

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/repos/XXXXXX/versions/XXXXXX/dependencies