Proposed OpenAPI Specification for PhyloPic 2.0

phylopic-swagger.json

{
	"swagger": "2.0",
	"info":
	{
		"title": "PhyloPic",
		"description": "PhyloPic is a database of free silhouette images of life forms, available for reuse under a Public Domain or Creative Commons license.",
		"termsOfService": "http://phylopic.org/terms/",
		"contact":
		{
			"name": "Mike Keesey",
			"email": "keesey@gmail.com"
		},
		"license":
		{
			"name": "Apache 2.0",
			"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
		},
		"version": "2.0.0"
	},
	"schemes": ["https"],
	"host": "phylopic.org",
	"basePath": "/api",
	"consumes": ["application/json"],
	"produces": ["application/json"],
	"paths":
	{
		"/accounts":
		{
			"post":
			{
				"summary": "Creates a new user account.",
				"operationId": "createAccount",
				"parameters":
				[
					{
						"name": "payload",
						"in": "body",
						"schema":
						{
							"type": "object",
							"required": [
								"allow_contact",
								"email",
								"name_family",
								"name_given",
								"password"
							],
							"properties": {
								"allow_contact": {
									"type": "boolean"
								},
								"email": {
									"format": "email",
									"type": "string"
								},
								"name_family": {
									"minLength": 1,
									"type": "string"
								},
								"name_given": {
									"minLength": 1,
									"type": "string"
								},
								"password": {
									"minLength": 8,
									"type": "string"
								}
							}
						}
					}
				]
			}
		}
	},
	"parameters":
	[
		{
			"name": "fields",
			"in": "query",
			"description": "A comma-separated list of the fields to include. If omitted, all are included.",
			"required": false,
			"type": "array",
			"items":
			{
				"type": "string"
			},
			"collectionFormat": "csv",
			"uniqueItems": true
		},
		{
			"name": "limit",
			"in": "query",
			"description": "The maximum number of items to list.",
			"required": false,
			"default": 32,
			"type": "number",
			"format": "byte",
			"maximum": 128,
			"minimum": 1
		},
		{
			"name": "previous_uid",
			"in": "query",
			"description": "Starts the list with the item directly after the one identified by this UUID.",
			"required": false,
			"type": "string",
			"format": "uuid"
		},
		{
			"name": "search",
			"in": "query",
			"description": "Constrains the list by searching for this text in relevent fields.",
			"required": false,
			"type": "string",
			"minLength": 2,
			"maxLength": 128
		},
	],
	"definitions":
	{
		"Entity":
		{
			"type": "object",
			"required": [ "uid" ],
			"properties":
			{
				"uid":
				{
					"type": "string",
					"format": "uuid"
				}
			}
		},
		"Image":
		{
			"allOf":
			[
				{
					"$ref": "#/definitions/Entity"
				},
				{
					"type": "object",
					"properties":
					{
						"credit":
						{
							"type": "string"
						},
						"general":
						{
							"$ref": "#/definitions/Name"
						},
						"licenseURL":
						{
							"type": "string",
							"format": "url"
						},
						"modified":
						{
							"type": "string",
							"format": "date-time"
						},
						"pngFiles":
						{
							"type": "array",
							"items":
							{
								"$ref": "#/definitions/PNGFile"
							}
						},
						"specific":
						{
							"$ref": "#/definitions/Name"
						},
						"submitted":
						{
							"type": "string",
							"format": "date-time"
						},
						"submitter":
						{
							"$ref": "#/definitions/User"
						},
						"svgFile":
						{
							"$ref": "#/definitions/SVGFile"
						},
						"taxa":
						{
							"type": "array",
							"items":
							{
								"$ref": "#/definitions/Taxon"
							}
						}
					}
				}
			]
		},
		"Name":
		{
			"allOf":
			[
				{
					"$ref": "#/definitions/Entity"
				},
				{
					"type": "object",
					"properties":
					{
						"html":
						{
							"type": "string"
						},
						"id":
						{
							"type": "string"
						},
						"root":
						{
							"type": "boolean"
						},
						"source":
						{
							"$ref": "#/definitions/Source"
						},
						"string":
						{
							"type": "string"
						}
					}
				}
			]
		},
		"PNGFile":
		{
			"type": "object",
			"required": [ "height", "url", "width" ],
			"properties":
			{
				"height":
				{
					"type": "integer",
					"format": "int32"
				},
				"url":
				{
					"type": "string",
					"format": "url"
				},
				"width":
				{
					"type": "integer",
					"format": "int32"
				}
			}
		},
		"Source":
		{
			"type": "object",
			"required": [ "namespace" ],
			"properties":
			{
				"namespace":
				{
					"type": "string",
					"format": "uri"
				},
				"title":
				{
					"type": "string"
				}
			}
		},
		"SVGFile":
		{
			"type": "object",
			"required": [ "url" ],
			"properties":
			{
				"url":
				{
					"type": "string",
					"format": "url"
				}
			}
		},
		"Taxon":
		{
			"type": "object",
			"properties":
			{
				"canonicalName":
				{
					"$ref": "#/definitions/Name"
				},
				"icon":
				{
					"$ref": "#/definitions/Image"
				},
				"illustrated":
				{
					"type": "boolean"
				},
				"names":
				{
					"type": "array",
					"items":
					{
						"$ref": "#/definitions/Name"
					}
				}
			}
		},
		"User":
		{
			"allOf":
			[
				{
					"$ref": "#/definitions/Entity"
				},
				{
					"type": "object",
					"properties":
					{
						"allowContact":
						{
							"type": "boolean"
						},
						"email":
						{
							"type": "string",
							"format": "email"
						},
						"familyName":
						{
							"type": "string"
						},
						"givenName":
						{
							"type": "string"
						}
					}
				}
			]
		}
	}
}