You should have your api keyset (two keys) ready. If not, generate them. These tokens are tied to your account, and thus, to your identity. Like all API keys, these are of course NON-TRANSFERABLE and should never be communicated to third-parties (and I won't call you and ask them either).
With these two keys in hand, you'll then need a request. Let's just issue a PUT on /users/test_user with "github=testgithub". In curl this should look like this:
$ curl -X PUT -d "github=testgithub" http://api.techshaker.com/users/test_user
Well, not really, we also need to authenticate. Authentification is done by adding your API_KEY ("the short one") to the headers as "X-API-KEY". Like this:
$ curl -X PUT -H "X-API-KEY: YOUR-API-KEY" -d "github=testgithub" http://api.techshaker.com/users/test_user
The next step will involve signing of your request, otherwise anyone can make requests in your name. Signing a request involve mixing all of its elements together and sorting them by key alphabetically. So for the above exemple, mixing all my request elements would give:
method=PUT&route=/users/test_user&github=testgithub
And sorted alphabetically:
github=testgithub&method=PUT&route=/users/test_user
This final string is what needs to be signed using HMac hash and SHA1 encryption and your API_SIG as the encryption key. You'll be returned a signed string to send to the server using the "X-API-SIGNATURE" header:
$ curl -X PUT -H "X-API-KEY: YOUR-API-KEY" -H "X-API-SIGNATURE: THAT-SIGNATURE" -d "github=testgithub" http://api.techshaker.com/users/test_user
{
"status": "success"
}
There you go! Though I would advise against using your shell to use the API :)
All errors are built the same way. Basically:
$ curl api.techshaker.com -v
< HTTP/1.1 401 Unauthorized
{
"error": "Unauthorized",
"statusCode": 401
}
$
Errors are sent in two ways:
- HTTP status code
- presence of "error" and "statusCode" keys
Relying on the HTTP status code is the correct way to use the API but sometimes accessing it is a luxury you don't have and some errors can just be too vague, so you can use these two keys to see if an error occured. Most of the time, the "error" is exactly the same as the HTTP response, but sometimes it will print out more detailed informations (see 422).
You're not authentified. Possible causes:
- Your request didn't contain an X-API-KEY in the header
- Your request didn't contain an X-API-SIGNATURE in the header
- You regenerated your keys and you X-API-KEY isn't valid anymore
- You did something wrong signing your request and it wasn't recognized as valid For security purposes, this error is NEVER detailed.
"I'm afraid I can't let you do that Dave.
Because you don't have the rights to issue a PUT/POST/DELETE request on this resource.
The desired resource doesn't exist.
"I will forget but won't forgive."
- My server
Something in your request wasn't acceptable. So this could mean:
No sub-resource on TechShaker will ever be called "foo".
If you call a PUT on /users/yourself/github and don't provide a "github=yourself" in PUT values, I won't understand what you're trying to achieve.
As cool as it looks, "y@_::-" is not a valid github username.
No PUT/POST values were sent, so nothing was done. This error is a nice trick to use as it will be issued AFTER a 404 or a 403 could happen. Thus, a PUT /resource with empty values is a "friendly" way of knowing in one call if the resource exists AND if you can edit it.
Get a list of users. Used for search.
Return the user pointed by screen_name.
GET /users/joshleaves
< HTTP/1.1 200 OK
{
"user": {
"id": 98996087,
"screen_name": "joshleaves",
"person_name": "Arnaud R.",
"profile_pic": "http://url2p.ro/file/pic.jpg",
"description": "Description",
"city": "Paris, FR",
"github": "joshleaves",
"website": "http://dreamleaves.org",
"entities": [
{
"url": "techshaker",
"name": "TechShaker",
"role": "Founder",
"profile_pic": "http://url2p.ro/file/pic.jpg"
}
]
}
Modifies multiple fields. Field keys can be: 'city', 'website', 'linkedin' or 'github'.
PUT /users/joshleaves "github=foo"
< HTTP/1.1 200 OK
{
"status": "SUCCESS"
}
Modifies a single field. Values for :field can be: 'city', 'website', 'linkedin' or 'github'.
PUT /users/joshleaves/github "github=foo"
< HTTP/1.1 200 OK
{
"status": "SUCCESS"
}