Intro to Taddy’s API (2024)

Getting Started with our API

To get started using our API, follow these steps:

1. Signup for a developer account.

2. Login to the dashboard and get your API Key.

3. Follow the steps in the next section to make your first API request.

Hello World (Making your first request)

Go to api.taddy.org on your browser and copy & paste the below query:

{ getPodcastSeries(name:"The Daily"){ uuid name itunesId description imageUrl itunesInfo{ uuid baseArtworkUrlOf(size:640) } }}

One important thing to note is that all requests to our API need to be authenticated to get a successful response. Don’t worry, it's easy to setup, but that means you will need to pass in your User ID and API Key in the headers. For the api.taddy.org playground there is a ‘Headers’ section at the bottom of the screen, double click to open it up and add your values for the headers X-USER-ID and X-API-KEY there. (see Authentication section below if you run into any issues).

You can also follow along with the video below:

Authentication

All requests to our API need to be authenticated. To get your API Key, log in to the Taddy Dashboard, you will see a “Get my API Key” button, clicking on it will reveal your API Key

You now have both your User ID and API Key and you will need to add both of them to the headers whenever you make an API request. Use the X-USER-ID and X-API-KEY keys and pass in your information as the values.

headers: {"X-USER-ID": 7,"X-API-KEY": "96c5007c18858e86d..."}

GraphQL vs REST APIs

Most developers will be familiar with REST APIs, but Taddy uses a GraphQL API. While both REST & GraphQL architectures are used to build APIs, we want to go over some of the unique benefits of GraphQL.

Ability to write custom queries

The main difference is that with REST you go to multiple endpoints to get back different information on different topics. With GraphQL there is only 1 endpoint and you can write custom queries depending on what information you want to get back.

Ability to get back custom responses

The big benefit of writing custom queries is that you get to specify the information you want back in the response. For the example below the first query gets back a podcast’s name and description, but the second one gets back the last 10 episodes. Practically, what this means is that depending on your business requirements, you can request the exact fields you need for your business use-case.

Working with a GraphQL API

When working with a GraphQL API, you can either:

1. Use a GraphQL specific library (Recommended)

One big benefit of using a dedicated library built to work with GraphQL over using a standard http library is that it is built to make it even easier to work with the queries you send and the data you get back. Here are some popular GraphQL libraries for a some popular languages:

• Javascript: GraphQL request (also check out our example project).

• Python: Graphene

• Ruby: GraphQL client

• iOS: Apollo or Swift GraphQL

• Android: Apollo or GraphQL Kotlin

Note: For a full list of libraries supported for even more languages, please see: https://graphql.org/code/

2. Interact with our API using any http client

This below shows a example of a simple request to our API using curl. There are 3 important parts to the request:

• Sending a POST request to our GraphQL API Endpoint https://api.taddy.org

• Adding Content-Type: application/json , X-USER-ID & X-API-KEY in the headers.

• Sending the query you care about in the data field. You can read our Podcast API docs to find all the different types of queries you can use.

curl -X POST \https://api.taddy.org \-H "Content-Type: application/json" \-H "X-USER-ID: 7" \-H "X-API-KEY: 96c5007c18858e86d..." \-d '{ "query": "{ getPodcastSeries(name:\"This American Life\") { uuid name } }" }'

Note: Currently, there are no official Taddy SDKs at the moment. However, one of the benefits of GraphQL is that types are built into it. If the language you using supports types, use a GraphQL Specific Library. While not an SDK, types give you most of the practical benefits of an SDK.

Useful Tips

UUIDs

Every piece of content on Taddy has its own unique UUID and therefore you will be using UUIDs when interacting with our API. You can learn more about uuids on Wikipedia.

Caching

We cache results from our API, which is great for API performance. Moreover, if your API request gets a cached response, it does not count against your monthly API limit 🥳.

Pagination

Queries such as getPodcastSeries can return multiple pages of results. For example the query below returns information on a podcast and its latest 10 episodes. By default it returns the latest 10 episodes released but you can modify that by passing different parameters.

// by default "episodes" returns the last 10 episodes{ getPodcastSeries(name:"This American Life"){ uuid episodes{ uuid name description audioUrl } }}

// you can also pass in parameters for "episodes". // This will return the exact same results as above // as these are the default parameters{ getPodcastSeries(name:"This American Life"){ uuid episodes(sortOrder:LATEST, page:1, limitPerPage:10){ uuid name description audioUrl } }}

// to get the 2nd page of results (the next 10 episodes){ getPodcastSeries(name:"This American Life"){ uuid episodes(page:2){ uuid name description audioUrl } }}

GraphQL Errors

A successful response will have the information you requested in the data key.

{ "data": { "answer": 42 }}

However, when you get back an error, you get back an errors array, which returns a list of all the errors. Note the two values associated with each error: the code (a category code for the type of error) and the message (a helpful message to help you troubleshoot the error).

{ "errors": [ { "code": // An Error Code (We categorize errors using different codes) "message": // Helpful message to help you problem solve the error } ], "data": { "answer": null }}

Here is an example: (123 is not a valid uuid because a valid uuid has to be 36 characters long)

Possible Error Codes

• API_KEY_INVALID - The API Key or User ID you are using in your headers is invalid.

• API_RATE_LIMIT_EXCEEDED - You have exceeded your monthly quota of API requests.

• INVALID_QUERY_OR_SYNTAX - Your query is too complex or there is a spelling or syntax mistake somewhere in your query. Use the message value as a hint as to what can be fixed.

• BAD_USER_INPUT - One of the arguments you are passing in is invalid. Use the message value to get more details on what is invalid.

• QUERY_TOO_COMPLEX - The query you are passing in is too complex. Please simplify your query (by removing items from your query)

• REQUIRES_USER_AUTHENTICATION - You need to be be logged in to make that request.

• ACCESS_NOT_ALLOWED - You are not allowed to access this query or mutation.

• TADDY_SERVER_ERROR - Something is wrong on our end. We have systems in place to monitor this but also feel free to reach out to [emailprotected] if you are getting this error.

Example Project

More Links: