Right¶

A right controls which DSPs may distribute a given product, optionally scoped to territories and/or continents. Each right links a distributor to a product (distributed) and one or more DSPs, and is associated with a user email.

Lists Rights¶

GET https://domain.com/api/v1/rights

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 200 OK

{
  "data": [
    {
      "type": "rights",
      "id": "<ID>",
      "attributes": {
        "action": "add",
        "comments": null,
        "created-by": "user-email@user-email.com",
        "updated-by": "user-email@user-email.com",
        "user-email": "user-email@user-email.com",
        "created-at": "2023-08-11T20:45:30.000000Z",
        "updated-at": "2023-08-11T20:45:30.000000Z"
      },
      "relationships": {
        "distributor": {
          "links": {
            "related": "https://domain.com/api/v1/rights/<ID>/distributor",
            "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributor"
          }
        },
        "distributed": {
          "links": {
            "related": "https://domain.com/api/v1/rights/<ID>/distributed",
            "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributed"
          }
        },
        "territories": {
          "links": {
            "related": "https://domain.com/api/v1/rights/<ID>/territories",
            "self": "https://domain.com/api/v1/rights/<ID>/relationships/territories"
          }
        },
        "continents": {
          "links": {
            "related": "https://domain.com/api/v1/rights/<ID>/continents",
            "self": "https://domain.com/api/v1/rights/<ID>/relationships/continents"
          }
        },
        "dsps": {
          "links": {
            "related": "https://domain.com/api/v1/rights/<ID>/dsps",
            "self": "https://domain.com/api/v1/rights/<ID>/relationships/dsps"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/v1/rights/<ID>"
      }
    }
  ],
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 1,
      "perPage": 20,
      "to": 1,
      "total": 1
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://domain.com/api/v1/rights?page[number]=1&page[size]=20",
    "last": "https://domain.com/api/v1/rights?page[number]=1&page[size]=20"
  }
}

Filters¶

Filter	Example
ID	`/rights?filter[id]=1`
User email	`/rights?filter[user-email]=user@example.com`
Product ID	`/rights?filter[product-id]=42`

Get Right¶

GET https://domain.com/api/v1/rights/:id

Path Parameters¶

Name	Type	Description
id*	Number	Right ID

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 200 OK

{
  "data": {
    "type": "rights",
    "id": "<ID>",
    "attributes": {
      "action": "add",
      "comments": null,
      "created-by": "user-email@user-email.com",
      "updated-by": "user-email@user-email.com",
      "user-email": "user-email@user-email.com",
      "created-at": "2023-08-11T20:45:30.000000Z",
      "updated-at": "2023-08-11T20:45:30.000000Z"
    },
    "relationships": {
      "distributor": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/distributor",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributor"
        }
      },
      "distributed": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/distributed",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributed"
        }
      },
      "territories": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/territories",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/territories"
        }
      },
      "continents": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/continents",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/continents"
        }
      },
      "dsps": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/dsps",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/dsps"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/rights/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/rights/<ID>"
  }
}

Create Right¶

POST https://domain.com/api/v1/rights

On create, action must be add. At least one DSP is required. The product is referenced through the distributed relationship.

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Request Body¶

Name	Type	Required	Description
action	String	Yes	Must be `add` on create
user-email	String	Yes	Email responsible for this rights action
distributor	Object	Yes	Distributor resource (relationship)
distributed	Object	Yes	Product resource (relationship)
dsps	Array	Yes	DSP resources (relationship, at least one)
comments	String	No	Free-text notes
territories	Array	No	Territory resources (relationship)
continents	Array	No	Continent resources (relationship)

Response — 201 Created

{
  "data": {
    "type": "rights",
    "id": "<ID>",
    "attributes": {
      "action": "add",
      "comments": null,
      "created-by": "user-email@user-email.com",
      "updated-by": "user-email@user-email.com",
      "user-email": "user-email@user-email.com",
      "created-at": "2023-08-11T20:45:30.000000Z",
      "updated-at": "2023-08-11T20:45:30.000000Z"
    },
    "relationships": {
      "distributor": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/distributor",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributor"
        }
      },
      "distributed": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/distributed",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributed"
        }
      },
      "territories": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/territories",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/territories"
        }
      },
      "continents": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/continents",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/continents"
        }
      },
      "dsps": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/dsps",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/dsps"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/rights/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/rights/<ID>"
  }
}

Response — 422 Unprocessable Entity

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "detail": "The action field is required.",
      "source": {
        "pointer": "/data/attributes/action"
      },
      "status": "422",
      "title": "Unprocessable Entity"
    }
  ]
}

Update Right¶

PATCH https://domain.com/api/v1/rights/:id

Path Parameters¶

Name	Type	Description
id*	Number	Right ID

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Request Body¶

Name	Type	Required	Description
action	String	No	`add`
user-email	String	No	Email responsible for this rights action
comments	String	No	Free-text notes
distributor	Object	No	Distributor resource (relationship)
distributed	Object	No	Product resource (relationship)
dsps	Array	No	DSP resources (relationship)
territories	Array	No	Territory resources (relationship)
continents	Array	No	Continent resources (relationship)

Response — 200 OK

{
  "data": {
    "type": "rights",
    "id": "<ID>",
    "attributes": {
      "action": "add",
      "comments": null,
      "created-by": "user-email@user-email.com",
      "updated-by": "user-email@user-email.com",
      "user-email": "user-email@user-email.com",
      "created-at": "2023-08-11T20:45:30.000000Z",
      "updated-at": "2023-08-11T20:45:30.000000Z"
    },
    "relationships": {
      "distributor": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/distributor",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributor"
        }
      },
      "distributed": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/distributed",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/distributed"
        }
      },
      "territories": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/territories",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/territories"
        }
      },
      "continents": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/continents",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/continents"
        }
      },
      "dsps": {
        "links": {
          "related": "https://domain.com/api/v1/rights/<ID>/dsps",
          "self": "https://domain.com/api/v1/rights/<ID>/relationships/dsps"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/rights/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/rights/<ID>"
  }
}

Delete Right¶

DELETE https://domain.com/api/v1/rights/:id

Path Parameters¶

Name	Type	Description
id*	Number	Right ID

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 204 No Content (delete OK, empty body)

Response — 404 Not Found

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": "404",
      "title": "Not Found"
    }
  ]
}