Kippt's API documentation

This is Kippt's API documentation. We use the API for our own web frontend and you're free to use it for your own projects and hacks.

If you find an error in the documentation, file an issue or send a pull request.

Mailing list and questions

If you use Kippt's API, we invite you to join our mailing list. It's used for communicating changes and answering questions related to the API. To contact us directly, email us at [email protected].

Format

All data is returned in JSON format. Also all the data that is passed to the server, must be formatted as JSON message. To get JSONP-style responses, supply GET attribute callback. The callback parameter is the desired function name and must be alphanumeric.

Authentication

Part of the API requires authentication and in some cases authenticated users will receive more information (e.g. is_favorite status for Clip models). Easiest way to test the API is to open GET endpoint in Chrome with JSONView extension installed.

Supported authentication:

• Browser session
• HTTP Basic Auth
• API Token

Read more about authentication

Versioning

Kippt's API uses timestamp based versioning which will return API version for the given date. If there's breaking changes to API, user's are given few months time to migrate.

Read more about versioning

Interacting with the API

Kippt's API uses regular GET, POST, PUT and DELETE commands.

Making requests and error codes

Pagination

When multiple objects are returned, pagination is used.

Read more about pagination

Endpoints

As this API is also used for Kippt's web app, we have had to make few design compromises and most of the resources can be queried with both numeric and alphabetical identifiers.

Account

• GET /api/account/

Users

• GET /api/users/:user_id/
• GET /api/users/:user_id/followers/
• GET /api/users/:user_id/following/
• GET /api/users/:user_id/relationship/
• GET /api/users/:user_id/clips/
• GET /api/users/:user_id/clips/favorites/
• GET /api/users/:user_id/clips/likes/
• GET /api/users/:user_id/lists/
• GET /api/users/:user_id/lists/:list_id/
• GET /api/users/search/
• POST /api/users/:user_id/relationship/

Clips

• GET /api/clips/
• GET /api/clips/feed/
• GET /api/clips/favorites/
• GET /api/clips/:clip_id/
• GET /api/clips/:clip_id/comments/
• GET /api/clips/:clip_id/likes/
• GET /api/clips/search/
• PUT /api/clips/:clip_id/
• POST /api/clips/
• POST /api/clips/:clip_id/comments/
• POST /api/clips/:clip_id/likes/
• POST /api/clips/:clip_id/favorite/
• DELETE /api/clips/:clip_id/
• DELETE /api/clips/:clip_id/comments/:comment_id/
• DELETE /api/clips/:clip_id/favorite/
• DELETE /api/clips/:clip_id/likes/

Lists

• GET /api/lists/
• GET /api/lists/following/
• GET /api/lists/:list_id/
• GET /api/lists/:list_id/clips/
• GET /api/lists/:list_id/relationship/
• PUT /api/lists/:list_id/
• POST /api/lists/
• POST /api/lists/:list_id/relationship/
• DELETE /api/lists/:list_id/

Notifications

• GET /api/notifications/
• POST /api/notifications/

Objects

• User
• Clip
• List
• Comment
• Notification

Contribution

While designing Kippt's API, we looked how other well designed APIs are build and structured.

• Instagram - Instagram's API has extremely well designed social API with following, comments and likes. Social structure in Kippt's API is heavily influenced by Instagram
• GitHub - GitHub's API is one of the few which can be navigated with textual identifiers which makes linking of the API and the web frontend possible
• Foursquare - Foursquare uses timestamp based API versioning. So do we (v1 style versioning feels like boxed software).
• 500px - This API documentation borrows heavily from 500px's structure
• django-tastypie - Kippt's pagination design is borrowed from Tastypie