app/microservice/swagger.json
{
"swagger": "2.0",
"info": {
"title": "GFW Subscription API",
"description": "Global Forest Watch - Subscriptions API",
"version": "1.0.0"
},
"host": "example.vizzuality.com",
"schemes": [
"https",
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/vnd.api+json"
],
"basePath": "/api/v1",
"paths": {
"/subscriptions": {
"get": {
"summary": "Get subscriptions",
"description": "Returns subscriptions of the logged user\n**Is necesary authentication**\n### Example response\n```json\n{\n \"data\": [{\n \"type\": \"subscription\",\n \"id\": \"579fa00dad0efc0000c58000\",\n \"attributes\": {\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n },\n \"confirmed\": true\n }\n }, {\n \"type\": \"subscription\",\n \"id\": \"579f12cf10558d2a003e1150\",\n \"attributes\": {\n \"name\": \"brazil-fires-not-confirmed\",\n \"createdAt\": \"2016-08-03T10:26:32.412Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"wdpaid\": \"12345\",\n \"geostore\": null\n },\n \"confirmed\": false\n }\n }]\n}\n```\n",
"operationId": "getSubscriptions",
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"responses": {
"200": {
"description": "Subscriptions obtained",
"schema": {
"$ref": "#/definitions/SubscriptionAPI"
}
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
},
"post": {
"summary": "Create subscriptions.",
"description": "Create subscription to the logged user\n**Is necesary authentication**\n### Example response\n```json\n{\n \"data\": [{\n \"type\": \"subscription\",\n \"id\": \"579fa00dad0efc0000c58000\",\n \"attributes\": {\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n },\n \"confirmed\": true\n }\n }]\n}\n```\n",
"consumes": [
"application/json"
],
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"operationId": "createSubscription",
"parameters": [
{
"name": "subscription",
"in": "body",
"description": "Subscription to save\n#### Body example\n```json\n{\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n }\n}\n```\n",
"required": true,
"schema": {
"$ref": "#/definitions/SubscriptionCreate"
}
}
],
"responses": {
"200": {
"description": "The subscription created",
"schema": {
"$ref": "#/definitions/SubscriptionAPI"
}
},
"400": {
"description": "Validate error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
}
},
"/subscriptions/{id}": {
"get": {
"summary": "Get subscription by id",
"description": "Returns subscriptions of the logged user\n**Is necesary authentication**\n### Example URL request\n```\n{{host}}/subscriptions/ca38fa80a4ffa9ac6217a7e0bf71e6df\n```\n### Example response\n```json\n{\n \"data\": [{\n \"type\": \"subscription\",\n \"id\": \"579fa00dad0efc0000c58000\",\n \"attributes\": {\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n },\n \"confirmed\": true\n }\n }]\n}\n```\n",
"operationId": "getSubscription",
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of subscription to fetch",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Subscriptions obtained",
"schema": {
"$ref": "#/definitions/SubscriptionAPI"
}
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
},
"patch": {
"summary": "Update subscription.",
"description": "Update subscription.\n**Is necesary authentication**\n### Example URL request\n```\n{{host}}/subscriptions/ca38fa80a4ffa9ac6217a7e0bf71e6df\n```\n### Example response\n```json\n{\n \"data\": [{\n \"type\": \"subscription\",\n \"id\": \"579fa00dad0efc0000c58000\",\n \"attributes\": {\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n },\n \"confirmed\": true\n }\n }]\n}\n```\n",
"consumes": [
"application/json"
],
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"operationId": "updateSubscription",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of subscription to update",
"required": true,
"type": "string"
},
{
"name": "subscription",
"in": "body",
"description": "New data of the subscription\n#### Body example\n```json\n{\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n }\n}\n```\n",
"required": true,
"schema": {
"$ref": "#/definitions/SubscriptionCreate"
}
}
],
"responses": {
"200": {
"description": "The subscription updated",
"schema": {
"$ref": "#/definitions/SubscriptionAPI"
}
},
"400": {
"description": "Validate error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
},
"delete": {
"summary": "Delete subscription.",
"description": "Delete subscription.\n**Is necesary authentication**\n### Example URL request\n```\n{{host}}/subscriptions/ca38fa80a4ffa9ac6217a7e0bf71e6df\n```\n### Example response\n```json\n{\n \"data\": [{\n \"type\": \"subscription\",\n \"id\": \"579fa00dad0efc0000c58000\",\n \"attributes\": {\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n },\n \"confirmed\": true\n }\n }]\n}\n```\n",
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"operationId": "deleteSubscription",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of subscription to delete",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "The subscription deleted",
"schema": {
"$ref": "#/definitions/SubscriptionAPI"
}
},
"400": {
"description": "Validate error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
}
},
"/subscriptions/{id}/confirm": {
"get": {
"summary": "Confirm subscription\n**Is necesary authentication**\n### Example URL request\n```\n{{host}}/subscriptions/ca38fa80a4ffa9ac6217a7e0bf71e6df/confirm\n```\n",
"description": "Confirm subscription",
"operationId": "confirmSubscription",
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of subscription to confirm",
"required": true,
"type": "string"
}
],
"responses": {
"302": {
"description": "Subscription confirmed successfully"
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
}
},
"/subscriptions/{id}/send_confirmation": {
"get": {
"description": "Resend confirmation of subscription\n**Is necesary authentication**\n",
"operationId": "sendConfirmation",
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of subscription to confirm",
"required": true,
"type": "string"
}
],
"responses": {
"302": {
"description": "Subscription confirmed successfully"
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
}
},
"/subscriptions/{id}/unsubscribe": {
"get": {
"summary": "Remove subscription",
"description": "Remove subscription\n**Is necesary authentication**\n### Example URL request\n```\n{{host}}/subscriptions/ca38fa80a4ffa9ac6217a7e0bf71e6df/unsubscribe\n```\n### Example response\n```json\n{\n \"data\": [{\n \"type\": \"subscription\",\n \"id\": \"579fa00dad0efc0000c58000\",\n \"attributes\": {\n \"name\": \"brazil-fires\",\n \"createdAt\": \"2016-08-03T10:26:32.409Z\",\n \"userId\": \"573c0015c0a1a601103bcccb\",\n \"resource\": {\n \"type\": \"EMAIL\",\n \"content\": \"vizz@vizzuality.com\"\n },\n \"datasets\": [\"viirs-active-fires\"],\n \"params\": {\n \"iso\": {\n \"region\": null,\n \"country\": \"BRA\"\n },\n \"geostore\": null\n },\n \"confirmed\": true\n }\n }]\n}\n```\n",
"operationId": "unsubscribeSubscription",
"produces": [
"application/vnd.api+json"
],
"tags": [
"SUBSCRIPTION"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of subscription to confirm",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Subscription removed",
"schema": {
"$ref": "#/definitions/SubscriptionAPI"
}
},
"500": {
"description": "Unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Errors"
}
}
}
}
}
},
"definitions": {
"Errors": {
"type": "object",
"description": "Errors",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/definitions/Error"
}
}
}
},
"Error": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32",
"description": "A unique identifier for this particular occurrence of the problem."
},
"links": {
"type": "object",
"description": "A links object",
"properties": {
"about": {
"type": "string",
"description": "A link that leads to further details about this particular occurrence of the problem."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code applicable to this problem, expressed as a string value"
},
"code": {
"type": "string",
"description": "An application-specific error code, expressed as a string value"
},
"title": {
"type": "string",
"description": "A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization."
},
"detail": {
"type": "string",
"description": "A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized"
},
"source": {
"type": "object",
"description": "An object containing references to the source of the error, optionally including any of the following members",
"properties": {
"pointer": {
"type": "string",
"description": "A JSON Pointer [RFC6901] to the associated entity in the request document"
},
"parameter": {
"type": "string",
"description": "A string indicating which URI query parameter caused the error."
}
}
},
"meta": {
"type": "object",
"description": "A meta object containing non-standard meta-information about the error."
}
}
},
"SubscriptionAPI": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/Subscription"
}
}
}
},
"Subscription": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Resource type"
},
"id": {
"type": "string",
"description": "Resource id"
},
"attributes": {
"properties": {
"schema": {
"$ref": "#/definitions/SubscriptionData"
}
}
}
}
},
"SubscriptionData": {
"type": "object",
"required": [
"name",
"resource",
"datasets",
"params"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the subscription"
},
"resource": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Subscription type (EMAIL, URL)"
},
"content": {
"type": "string",
"description": "In mail case, is the user email"
}
}
},
"datasets": {
"type": "string",
"description": "Datasets that subscribes (example => viirs-active-fires, glad-alerts)"
},
"params": {
"type": "object",
"properties": {
"iso": {
"type": "object",
"properties": {
"country": {
"type": "string",
"description": "ISO code of the country"
},
"region": {
"type": "number",
"description": "Number code of the region"
}
}
},
"wdpaid": {
"type": "number",
"description": "Id of the protected area"
},
"use": {
"type": "string",
"description": "Name of the use (example=> mining, oilpalm, fiber, gfw_logging, etc)"
},
"useid": {
"type": "number",
"description": "id of the use"
},
"geostore": {
"type": "string",
"description": "Id of the geostore"
}
}
}
}
},
"SubscriptionCreate": {
"allOf": [
{
"$ref": "#/definitions/SubscriptionData"
},
{
"type": "object",
"properties": {
"confirmed": {
"type": "boolean",
"description": "If the subscription is confirmed"
},
"createdAt": {
"type": "string",
"description": "Creation date"
}
}
}
]
}
}
}