API Basics

Table of Contents

We have tried very hard to keep this api as simple as possible. In doing so, we've created standard request and response objects

All requests are done with a basic HTTP POST or GET. Either can be used for any endpoint, though there are some situations where one works better than the other. For instance, just running a few tests from your browser? Yeah, GET is fine. Sending a fax? Please use POST. A little bit of forethought goes a long way. Ultimately, on your servers, we highly suggest just making everything a POST.

Example Request
curl "https://apiv1.teleapi.net/dids/list?token=<your api key>"
#prints
{"code":"200","status":"success","data":"[ array of did objects ]"}

Pretty simple so far, right? Ok, let's take a look at the standard responses

Example responses
Success
{
    "code": "200",
    "status": "success",
    "data": "whatever the api is sending you"
}
Error
{
    "code": "400",
    "status": "error",
    "data": "what you did wrong"
}

Every single response will have 3 fields: code, status, data. All of them. No exceptions. If you find an exception, let us know and we'll make sure the right person is properly humiliated.

code

Generally speaking this will be something close to what you might expect from an HTTP code. For instance, 200 is used for success. Always. 400 is a client (you) error. 500 is something on our side. 403 if you're trying to do something forbidden. Really, those 4 are probably what you'll see the most. If you see something else, let me google that for you.

status

Status is the human readable version of code. Or, sometimes, your check for what kind of 400 failure you have. That sort of stuff. The vast majority of responses it will either be "success" or "fail". But, don't rely on it being one of those two. For your first tier error checking, use code.

data

This is where the magic is. And it could be anything. Depending on what you're asking for, it might be a string, a json object, something else.. This is where you would look for the specific endpoint documentation to know what exactly to expect. Though, I will say, if code == 400 || code == 500 you can expect data == "A nice message about why things broke"

Missing variable

Let's face it, there is going to be that situation where you try to something but forget to send a variable. We've got you covered. If this happens you will see something to the effect of

{
    "code": 400,
    "status": "error",
    "data": "Missing variable: <what you forgot>"
}

Simply fill out that parameter, and send again. There's no shame. We all do it.

And that's it

Get the idea of a request and response in your mind and you're ready to go. Remember that every api call will require a token, excepting /auth which requires your api key (so you can get a token). Go forth and do great things.