diff options
author | Nihad Abbasov <narkoz.2008@gmail.com> | 2012-07-05 17:57:45 +0400 |
---|---|---|
committer | Nihad Abbasov <narkoz.2008@gmail.com> | 2012-07-05 17:57:45 +0400 |
commit | f086676b7c02dc9958fa9c7f6135142523f65bfc (patch) | |
tree | c737221ea51a911aef40ce93e57c1fe0efa22ef5 /doc | |
parent | 5f38f67247786988c8fa1d86fe0afdd411360b27 (diff) |
add docs for existing API
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/README.md | 29 | ||||
-rw-r--r-- | doc/api/projects.md | 270 | ||||
-rw-r--r-- | doc/api/users.md | 90 |
3 files changed, 389 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md new file mode 100644 index 00000000000..dcf75afda1f --- /dev/null +++ b/doc/api/README.md @@ -0,0 +1,29 @@ +# Gitlab API + +All API requests require authentication. You need to pass `private_token` parameter to authenticate. + +To get or reset your token visit your profile. + +If no or invalid `private_token` provided error message will be returned with status code 401: + +```json +{ + "message": "401 Unauthorized" +} +``` + +API requests should be prefixed with `api` and the API version. +API version is equal to Gitlab major version number and defined in `lib/api.rb`. + +Example of valid API request: + +``` +GET http://example.com/api/v2/projects?private_token=QVy1PB7sTxfy4pqfZM1U +``` + +The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL. + +## Contents + ++ [Users](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/users.md) ++ [Projects](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/projects.md) diff --git a/doc/api/projects.md b/doc/api/projects.md new file mode 100644 index 00000000000..465868db36e --- /dev/null +++ b/doc/api/projects.md @@ -0,0 +1,270 @@ +## List projects + +Get a list of authenticated users' projects. + +``` +GET /projects +``` + +```json +[ + { + "id": 3, + "code": "rails", + "name": "rails", + "description": null, + "path": "rails", + "default_branch": "master", + "owner": { + "id": 1, + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z" + }, + "private": true, + "issues_enabled": false, + "merge_requests_enabled": false, + "wall_enabled": true, + "wiki_enabled": true, + "created_at": "2012-05-23T08:05:02Z" + }, + { + "id": 5, + "code": "gitlab", + "name": "gitlab", + "description": null, + "path": "gitlab", + "default_branch": "api", + "owner": { + "id": 1, + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z" + }, + "private": true, + "issues_enabled": true, + "merge_requests_enabled": true, + "wall_enabled": true, + "wiki_enabled": true, + "created_at": "2012-05-30T12:49:20Z" + } +] +``` + +## Single project + +Get an authenticated user's project. + +``` +GET /projects/:id +``` + +Parameters: + ++ `id` (required) - The code name of a project + +```json +{ + "id": 5, + "code": "gitlab", + "name": "gitlab", + "description": null, + "path": "gitlab", + "default_branch": "api", + "owner": { + "id": 1, + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z" + }, + "private": true, + "issues_enabled": true, + "merge_requests_enabled": true, + "wall_enabled": true, + "wiki_enabled": true, + "created_at": "2012-05-30T12:49:20Z" +} +``` + +## Project repository branches + +Get a list of project repository branches. + +``` +GET /projects/:id/repository/branches +``` + +Parameters: + ++ `id` (required) - The code name of a project + +```json +[ + { + "name": "master", + "commit": { + "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", + "parents": [ + { + "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8" + } + ], + "tree": "46e82de44b1061621357f24c05515327f2795a95", + "message": "add projects API", + "author": { + "name": "John Smith", + "email": "john@example.com" + }, + "committer": { + "name": "John Smith", + "email": "john@example.com" + }, + "authored_date": "2012-06-27T05:51:39-07:00", + "committed_date": "2012-06-28T03:44:20-07:00" + } + } +] +``` + +## Project repository tags + +Get a list of project repository tags. + +``` +GET /projects/:id/repository/tags +``` + +Parameters: + ++ `id` (required) - The code name of a project + +```json +[ + { + "name": "v1.0.0", + "commit": { + "id": "2695effb5807a22ff3d138d593fd856244e155e7", + "parents": [ + + ], + "tree": "38017f2f189336fe4497e9d230c5bb1bf873f08d", + "message": "Initial commit", + "author": { + "name": "John Smith", + "email": "john@example.com" + }, + "committer": { + "name": "Jack Smith", + "email": "jack@example.com" + }, + "authored_date": "2012-05-28T04:42:42-07:00", + "committed_date": "2012-05-28T04:42:42-07:00" + } + } +] +``` + +# Project Snippets + +## List snippets + +Not implemented. + +## Single snippet + +Get a project snippet. + +``` +GET /projects/:id/snippets/:snippet_id +``` + +Parameters: + ++ `id` (required) - The code name of a project ++ `snippet_id` (required) - The ID of a project's snippet + +```json +{ + "id": 1, + "title": "test", + "file_name": "add.rb", + "author": { + "id": 1, + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z" + }, + "expires_at": null, + "updated_at": "2012-06-28T10:52:04Z", + "created_at": "2012-06-28T10:52:04Z" +} +``` + +## Snippet content + +Get a raw project snippet. + +``` +GET /projects/:id/snippets/:snippet_id/raw +``` + +Parameters: + ++ `id` (required) - The code name of a project ++ `snippet_id` (required) - The ID of a project's snippet + +## New snippet + +Create a new project snippet. + +``` +POST /projects/:id/snippets +``` + +Parameters: + ++ `id` (required) - The code name of a project ++ `title` (required) - The title of a snippet ++ `file_name` (required) - The name of a snippet file ++ `lifetime` (optional) - The expiration date of a snippet ++ `code` (required) - The content of a snippet + +Will return created snippet with status `201 Created` on success, or `404 Not found` on fail. + +## Edit snippet + +Update an existing project snippet. + +``` +PUT /projects/:id/snippets/:snippet_id +``` + +Parameters: + ++ `id` (required) - The code name of a project ++ `snippet_id` (required) - The ID of a project's snippet ++ `title` (optional) - The title of a snippet ++ `file_name` (optional) - The name of a snippet file ++ `lifetime` (optional) - The expiration date of a snippet ++ `code` (optional) - The content of a snippet + +Will return updated snippet with status `200 OK` on success, or `404 Not found` on fail. + +## Delete snippet + +Update an existing project snippet. + +``` +DELETE /projects/:id/snippets/:snippet_id +``` + +Parameters: + ++ `id` (required) - The code name of a project ++ `snippet_id` (required) - The ID of a project's snippet + +Status code `200` will be returned on success. diff --git a/doc/api/users.md b/doc/api/users.md new file mode 100644 index 00000000000..b9b04dc5399 --- /dev/null +++ b/doc/api/users.md @@ -0,0 +1,90 @@ +## List users + +Get a list of users. + +``` +GET /users +``` + +```json +[ + { + "id": 1, + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z", + "bio": null, + "skype": "", + "linkedin": "", + "twitter": "", + "dark_scheme": false, + "theme_id": 1 + }, + { + "id": 2, + "email": "jack@example.com", + "name": "Jack Smith", + "blocked": false, + "created_at": "2012-05-23T08:01:01Z", + "bio": null, + "skype": "", + "linkedin": "", + "twitter": "", + "dark_scheme": true, + "theme_id": 1 + } +] +``` + +## Single user + +Get a single user. + +``` +GET /users/:id +``` + +Parameters: + ++ `id` (required) - The ID of a user + +```json +{ + "id": 1, + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z", + "bio": null, + "skype": "", + "linkedin": "", + "twitter": "", + "dark_scheme": false, + "theme_id": 1 +} +``` + +## Current user + +Get currently authenticated user. + +``` +GET /user +``` + +```json +{ + "id": 1, + "email": "john@example.com", + "name": "John Smith", + "blocked": false, + "created_at": "2012-05-23T08:00:58Z", + "bio": null, + "skype": "", + "linkedin": "", + "twitter": "", + "dark_scheme": false, + "theme_id": 1 +} +``` |