Summary

MediaValet.API is a RESTful service that implements hypermedia which supplies the data to a client wanting to consume MediaValet data. The service applies business rules, permission rules, and other data processing to standardize what is returned from the service.

Authentication and access control is done with OAuth2 using bearer tokens. All requests, and data are checked against the user specified in an access token that is passed as part of the the request. If they user has access to the resource that is being requested, the request will be allowed, otherwise a 401 (Unauthorized) error will be returned. Additionally, any data that the user does not have permissions for will be suppressed..

Access to the Service requires SSL. If a non-SSL request is received the service returns a 403 (Forbidden) error..

Authentication

For information on how to authenticate, please refer to the documentation.

Authorization

Authorization is required on every request to the API.

To authenticate, the request should include an Authorization entry in the header. The data for this entry should be "Bearer {authorization token}", where the token is the token recieved from the authentication request.

The API uses the token to determine if the user it represents has access to the data that is being requested.

API Responses

All responses from the API have the same structure which includes a mix of entity data and meta-data details. The layout of the document is:

{
    "ApiVersion": "1.0.0.0",
    "Meta": {
        "MetaInformation": {},
        "Warnings": [],
        "Errors": [],
        "CreatedOn": "2014-01-01T00:00:00Z"
      },
      "RecordCount": {
        "TotalRecordsFound": 0,
        "StartingRecord": 1,
        "RecordsReturned": 10
      },
      "Payload": {}
}

Definitions

  • ApiVersion: The version of the API that processed the request.
  • Meta: Data that can be useful for understanding the data. Such information could be the search parameters, elapsed time for the request, date/time the request was processed, etc. This data is also dependent on the endpoint that was queried, and the fields could change accordingly.
  • RecordCount: Record counts related to this request.
  • Payload: The serialized result for the request.

Querystring Parameters

These parameters can be used on any end-point within the API.  They are not case sensitive.

Count

The count element specifies the number of records to be returned for the search.

The default value is 50.

To set the count, include count={long} to the query string.

https://api-california.mediavalet.net/{entity}?filters={search}&count=25

Exclude

This feature has not been implemented yet.

The exclude section allows for specific fields, or a list of fields to be removed from the response. When included in the request, the response will contain all fields, except the ones listed. If a field is not found, a warning is placed into the response, and the exclusion is ignored.

If a field is in both the Include and the Exclude section, a 400 (Bad Request) Status Code will be returned with an explanation of the error.

https://api-california.mediavalet.net/entity?exclude=fieldWithLotsOfData

Filters

For information on searching, see the search and filters document

Include

This feature has not been implemented yet.

The include section allows for specific fields, or a list of fields to be returned. When included in the request, the response will only contain the fields listed. If a field is not found, a warning is placed into the response, and the inclusion is ignored. If there is only one field in the Include section, and that field is not found, a warning will be placed in the warning section, and an empty result set will be returned.

If a field is in both the Include and the Exclude section, a 400 (Bad Request) Status Code will be returned with an explanation of the error.

https://api-california.mediavalet.net/entity?include=id,FieldOne

Max-Length

This feature has not been implemented yet.

The max-length element allows for truncation of fields within the response. The syntax will be max-length=field:value.

It is valid to have more than one field truncated per response. Each field should be separated by a comma.

When a field is not found, a warning will be placed in the warnings section, and the truncation for that field will be ignored.

https://api-california.mediavalet.net/entity?max-length=FirstField:256,OtherField:25

Offset

Adding an offset entity to the querystring skips the specified number of records in the result set.

The default value is 0.

To set the offset, include offset={long value} to the query string.

https://api-california.mediavalet.net/{entity}?q={search}&offset=10