Down below you'll find a quick and simple introduction on how to use the api for mify.me. I'll cover the possible requests that are accepted, and along with that the return-values that come with the specific request.
On an initial note it's worth mentioning that the api, for now, doesn't require any authentication to use. However, the server will throttle if you exceed the request-rate (currently at 15r/s) from the same ip-address.
With that said, let's move on to the actual documentation!
In our example we'll shorten the url http://google.com, to do this we'll forward this HTTP-post request;
url=http://google.com
to http://api.mify.me/url, and in return the server will give us this in response;
{"urlID":"14","url":"http:\/\/mify.me\/u\/14"}
In the response, urlID is the id given to identify the shortened url (eg. for grabbing stats about it later on) and url is the the actual url used for redirection.
If we would like to use a custom id for the shortened url, we could add another parameter to the POST-request, like this;
url=http://google.com&custom=google
And in return, we'll get:
{"urlID":"google","url":"http:\/\/mify.me\/u\/google"}
The given urlID "google" could be used anywhere instead of the regular one (which isn't given when you use a custom one).
If we remember the id of a shortened url, but not where it leads, we could forward this request to get the url behind the link (using the id provided in the previous example);
http://api.mify.me/url/14
This will give us a response like this:
{"urlID":"14","url":"http:\/\/google.com"}
In where urlID is the same id that we requested the url for and url is the url "behind" the id.
If we're interested about some statistics about a shortened url, we can use the following request to get some numbers back;
http://api.mify.me/url/stats/14
Wich in return will give us;
{"urlID":"14","totalClicks":"1","clicksLastWeek":"1"}
As before, urlID is the same id that we requested the url for, and totalClicks is, as the name suggests, the total number of clicks that given url has. clicksLastWeek contains the amount of clicks that id has in the last seven days.
So far so good, right? There might be some errors if something broke behind the scenes, or if the url/id is incorrect. Following is a list of returns when something's not right.
When posting an url:
{"error":"Invalid url.","url":"http:\/\/google.comm","errno":"200"}
Where error contains the message provided by the api, and url the url that was submitted.
{"error":"Failed to submit the url to the database.","errno":"201"}
This "should" never happen, but it indicates some sort of failure on the backend. Keep on trying is the suggestion here.
When using custom-id's, the following errors could occur:
{"error":"The provided custom-url is invalid.","errno":"210"}
Which means that the custom url contained illegal characters, valid ones are a-z A-Z and 0-9.
{"error":"The custom url already exists in the database.","errno":"211"}
Which means that the custom url is already in use by some other url, retry with a new one.
When decoding an already shortened url:
{"error":"Invalid id provided for the URL.","errno":"100"}
As the message states, the id provided for decoding isn't a valid one.
{"error":"No url found for this id.","errno":"101"}
Similar to the error above, but this one means that the id itself was valid, however no url was found on it.
General errors:
The only "general" error out there at the moment is a 503 error when too many requests are done in the given timeframe. Slow down a bit and try again later.
There's one more in the code, if you encounter a message like this:
{"error":"Something is really wrong.","errno":"0"}
Something is, indeed, really wrong. The only thing I'd advice you to do is try again.