The Oovvuu API is a graphql based API, we have a fully documented and traversable schema which can be publically viewed at:
https://api-discovery.oovvuu.media
with the API being publicly available at:
https://api.oovvuu.media/v1/graphql/
NOTE: you will need to have an Oovvuu account before you can access it however, please contact us at https://oovvuu.com/contact/
Headers
When using the API you will need to ensure that you have the right headers in order to be able to access the API.
Name | Description |
Authorization | Will be of the format `bearer {token}` |
Content-Type | application/json |
Accept-Encoding | application/json |
The Authorization header will need to use the Auth0 token, you can get this from the correct SDk or the compass application. Please refer to the Authorization Page.
GraphQL
The Public API is a GraphQL based API that allows programatic interaction with the Oovvuu platform. If you wish to find out more about GraphQL then please visit: https://graphql.org/
Enumerated types
Oovvuu utilises enumerated types for status codes, menu options and several other areas of the API. As GraphQL is a defined schema we can search and list the enumerations. For example to receive the list of Genres we can do
query {
__type(name: "Genre") {
name
enumValues {
name
}
}
}
Queries and Mutations
Following the GraphQL specification we respect the query and mutation types in the schema, all queries for information are done using 'Query' and all changes to information are done using 'Mutation'.
Error handling
When errors occur within the request to the Oovvuu Platform or unexpected errors occur there will be two main types of responses sent.
HTTP Response
The HTTP response is the first type of error code that should be checked as this is still the basis of the communication protocol. The Oovvuu Public API respects and sends the Standard HTTP error codes, the full comprehensive list of codes and their meanings can be found her https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
However the primary ones that an external application should be concerned with when dealing with the Oovvuu Pubilc API are:
Error Code |
Meaning |
Resolution |
---|---|---|
HTTP 200 |
Success |
|
HTTP 201 |
Success |
|
HTTP 400 |
Bad Request |
Please review the data being sent to the API as it is incorrect, rectify the data and resend request |
HTTP 401 |
Unauthorised |
Have the user log out and log back in |
HTTP 403 |
Forbidden |
The user is authorised however does not have permission to perform this action. Update the user roles with correct privileges |
HTTP 404 |
Not Found |
Check the ID of resource you are asking for and resend the request with new ID |
HTTP 500 |
Internal Server Error |
An error has occured within the Oovvuu platform. This is an unexpected error, the user should try again in 5 minutes |
HTTP 502 |
Bad Gateway |
The service you have requested does not exist, please check the url and resend the request |
HTTP 503 |
Service Unavailable |
The Public API is experiencing an outage. Check the service status page and if the problem persists raise support request with Oovvuu |
GraphQL Error
In the event of an HTTP 500 error oovvuu will also provide an Errors object within the response. Apollo have a robust error handling mechanism that the Oovvuu Pubilc API also follows, and it has been very documented here:
https://www.apollographql.com/docs/apollo-server/data/errors/
For example a typical response might be
{
data: {
userInputError: null
},
errors: {
message: "User Input Error, validation failed for field 'preferredName'",
path: [""],
extensions: {
code: ""
}
}