Download as
Browse Code »

Commit bf519f64b007364242648852dc8220f3a270c3cc

Authored by Dmitriy Zaporozhets
2 parents df6a75d5 4083cfa4
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

Merge pull request #1043 from NARKOZ/api 

API docs
Showing 5 changed files with 399 additions and 2 deletions   Show diff stats
doc/api/README.md 0 → 100644
  Diff comments   View file @bf519f6
... ... @@ -0,0 +1,29 @@
  1 +# Gitlab API
  2 +
  3 +All API requests require authentication. You need to pass `private_token` parameter to authenticate.
  4 +
  5 +To get or reset your token visit your profile.
  6 +
  7 +If no or invalid `private_token` provided error message will be returned with status code 401:
  8 +
  9 +```json
  10 +{
  11 + "message": "401 Unauthorized"
  12 +}
  13 +```
  14 +
  15 +API requests should be prefixed with `api` and the API version.
  16 +API version is equal to Gitlab major version number and defined in `lib/api.rb`.
  17 +
  18 +Example of valid API request:
  19 +
  20 +```
  21 +GET http://example.com/api/v2/projects?private_token=QVy1PB7sTxfy4pqfZM1U
  22 +```
  23 +
  24 +The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
  25 +
  26 +## Contents
  27 +
  28 ++ [Users](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/users.md)
  29 ++ [Projects](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/projects.md)
... ...
doc/api/projects.md 0 → 100644
  Diff comments   View file @bf519f6
... ... @@ -0,0 +1,270 @@
  1 +## List projects
  2 +
  3 +Get a list of authenticated users' projects.
  4 +
  5 +```
  6 +GET /projects
  7 +```
  8 +
  9 +```json
  10 +[
  11 + {
  12 + "id": 3,
  13 + "code": "rails",
  14 + "name": "rails",
  15 + "description": null,
  16 + "path": "rails",
  17 + "default_branch": "master",
  18 + "owner": {
  19 + "id": 1,
  20 + "email": "john@example.com",
  21 + "name": "John Smith",
  22 + "blocked": false,
  23 + "created_at": "2012-05-23T08:00:58Z"
  24 + },
  25 + "private": true,
  26 + "issues_enabled": false,
  27 + "merge_requests_enabled": false,
  28 + "wall_enabled": true,
  29 + "wiki_enabled": true,
  30 + "created_at": "2012-05-23T08:05:02Z"
  31 + },
  32 + {
  33 + "id": 5,
  34 + "code": "gitlab",
  35 + "name": "gitlab",
  36 + "description": null,
  37 + "path": "gitlab",
  38 + "default_branch": "api",
  39 + "owner": {
  40 + "id": 1,
  41 + "email": "john@example.com",
  42 + "name": "John Smith",
  43 + "blocked": false,
  44 + "created_at": "2012-05-23T08:00:58Z"
  45 + },
  46 + "private": true,
  47 + "issues_enabled": true,
  48 + "merge_requests_enabled": true,
  49 + "wall_enabled": true,
  50 + "wiki_enabled": true,
  51 + "created_at": "2012-05-30T12:49:20Z"
  52 + }
  53 +]
  54 +```
  55 +
  56 +## Single project
  57 +
  58 +Get an authenticated user's project.
  59 +
  60 +```
  61 +GET /projects/:id
  62 +```
  63 +
  64 +Parameters:
  65 +
  66 ++ `id` (required) - The code name of a project
  67 +
  68 +```json
  69 +{
  70 + "id": 5,
  71 + "code": "gitlab",
  72 + "name": "gitlab",
  73 + "description": null,
  74 + "path": "gitlab",
  75 + "default_branch": "api",
  76 + "owner": {
  77 + "id": 1,
  78 + "email": "john@example.com",
  79 + "name": "John Smith",
  80 + "blocked": false,
  81 + "created_at": "2012-05-23T08:00:58Z"
  82 + },
  83 + "private": true,
  84 + "issues_enabled": true,
  85 + "merge_requests_enabled": true,
  86 + "wall_enabled": true,
  87 + "wiki_enabled": true,
  88 + "created_at": "2012-05-30T12:49:20Z"
  89 +}
  90 +```
  91 +
  92 +## Project repository branches
  93 +
  94 +Get a list of project repository branches.
  95 +
  96 +```
  97 +GET /projects/:id/repository/branches
  98 +```
  99 +
  100 +Parameters:
  101 +
  102 ++ `id` (required) - The code name of a project
  103 +
  104 +```json
  105 +[
  106 + {
  107 + "name": "master",
  108 + "commit": {
  109 + "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
  110 + "parents": [
  111 + {
  112 + "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
  113 + }
  114 + ],
  115 + "tree": "46e82de44b1061621357f24c05515327f2795a95",
  116 + "message": "add projects API",
  117 + "author": {
  118 + "name": "John Smith",
  119 + "email": "john@example.com"
  120 + },
  121 + "committer": {
  122 + "name": "John Smith",
  123 + "email": "john@example.com"
  124 + },
  125 + "authored_date": "2012-06-27T05:51:39-07:00",
  126 + "committed_date": "2012-06-28T03:44:20-07:00"
  127 + }
  128 + }
  129 +]
  130 +```
  131 +
  132 +## Project repository tags
  133 +
  134 +Get a list of project repository tags.
  135 +
  136 +```
  137 +GET /projects/:id/repository/tags
  138 +```
  139 +
  140 +Parameters:
  141 +
  142 ++ `id` (required) - The code name of a project
  143 +
  144 +```json
  145 +[
  146 + {
  147 + "name": "v1.0.0",
  148 + "commit": {
  149 + "id": "2695effb5807a22ff3d138d593fd856244e155e7",
  150 + "parents": [
  151 +
  152 + ],
  153 + "tree": "38017f2f189336fe4497e9d230c5bb1bf873f08d",
  154 + "message": "Initial commit",
  155 + "author": {
  156 + "name": "John Smith",
  157 + "email": "john@example.com"
  158 + },
  159 + "committer": {
  160 + "name": "Jack Smith",
  161 + "email": "jack@example.com"
  162 + },
  163 + "authored_date": "2012-05-28T04:42:42-07:00",
  164 + "committed_date": "2012-05-28T04:42:42-07:00"
  165 + }
  166 + }
  167 +]
  168 +```
  169 +
  170 +# Project Snippets
  171 +
  172 +## List snippets
  173 +
  174 +Not implemented.
  175 +
  176 +## Single snippet
  177 +
  178 +Get a project snippet.
  179 +
  180 +```
  181 +GET /projects/:id/snippets/:snippet_id
  182 +```
  183 +
  184 +Parameters:
  185 +
  186 ++ `id` (required) - The code name of a project
  187 ++ `snippet_id` (required) - The ID of a project's snippet
  188 +
  189 +```json
  190 +{
  191 + "id": 1,
  192 + "title": "test",
  193 + "file_name": "add.rb",
  194 + "author": {
  195 + "id": 1,
  196 + "email": "john@example.com",
  197 + "name": "John Smith",
  198 + "blocked": false,
  199 + "created_at": "2012-05-23T08:00:58Z"
  200 + },
  201 + "expires_at": null,
  202 + "updated_at": "2012-06-28T10:52:04Z",
  203 + "created_at": "2012-06-28T10:52:04Z"
  204 +}
  205 +```
  206 +
  207 +## Snippet content
  208 +
  209 +Get a raw project snippet.
  210 +
  211 +```
  212 +GET /projects/:id/snippets/:snippet_id/raw
  213 +```
  214 +
  215 +Parameters:
  216 +
  217 ++ `id` (required) - The code name of a project
  218 ++ `snippet_id` (required) - The ID of a project's snippet
  219 +
  220 +## New snippet
  221 +
  222 +Create a new project snippet.
  223 +
  224 +```
  225 +POST /projects/:id/snippets
  226 +```
  227 +
  228 +Parameters:
  229 +
  230 ++ `id` (required) - The code name of a project
  231 ++ `title` (required) - The title of a snippet
  232 ++ `file_name` (required) - The name of a snippet file
  233 ++ `lifetime` (optional) - The expiration date of a snippet
  234 ++ `code` (required) - The content of a snippet
  235 +
  236 +Will return created snippet with status `201 Created` on success, or `404 Not found` on fail.
  237 +
  238 +## Edit snippet
  239 +
  240 +Update an existing project snippet.
  241 +
  242 +```
  243 +PUT /projects/:id/snippets/:snippet_id
  244 +```
  245 +
  246 +Parameters:
  247 +
  248 ++ `id` (required) - The code name of a project
  249 ++ `snippet_id` (required) - The ID of a project's snippet
  250 ++ `title` (optional) - The title of a snippet
  251 ++ `file_name` (optional) - The name of a snippet file
  252 ++ `lifetime` (optional) - The expiration date of a snippet
  253 ++ `code` (optional) - The content of a snippet
  254 +
  255 +Will return updated snippet with status `200 OK` on success, or `404 Not found` on fail.
  256 +
  257 +## Delete snippet
  258 +
  259 +Delete existing project snippet.
  260 +
  261 +```
  262 +DELETE /projects/:id/snippets/:snippet_id
  263 +```
  264 +
  265 +Parameters:
  266 +
  267 ++ `id` (required) - The code name of a project
  268 ++ `snippet_id` (required) - The ID of a project's snippet
  269 +
  270 +Status code `200` will be returned on success.
... ...
doc/api/users.md 0 → 100644
  Diff comments   View file @bf519f6
... ... @@ -0,0 +1,90 @@
  1 +## List users
  2 +
  3 +Get a list of users.
  4 +
  5 +```
  6 +GET /users
  7 +```
  8 +
  9 +```json
  10 +[
  11 + {
  12 + "id": 1,
  13 + "email": "john@example.com",
  14 + "name": "John Smith",
  15 + "blocked": false,
  16 + "created_at": "2012-05-23T08:00:58Z",
  17 + "bio": null,
  18 + "skype": "",
  19 + "linkedin": "",
  20 + "twitter": "",
  21 + "dark_scheme": false,
  22 + "theme_id": 1
  23 + },
  24 + {
  25 + "id": 2,
  26 + "email": "jack@example.com",
  27 + "name": "Jack Smith",
  28 + "blocked": false,
  29 + "created_at": "2012-05-23T08:01:01Z",
  30 + "bio": null,
  31 + "skype": "",
  32 + "linkedin": "",
  33 + "twitter": "",
  34 + "dark_scheme": true,
  35 + "theme_id": 1
  36 + }
  37 +]
  38 +```
  39 +
  40 +## Single user
  41 +
  42 +Get a single user.
  43 +
  44 +```
  45 +GET /users/:id
  46 +```
  47 +
  48 +Parameters:
  49 +
  50 ++ `id` (required) - The ID of a user
  51 +
  52 +```json
  53 +{
  54 + "id": 1,
  55 + "email": "john@example.com",
  56 + "name": "John Smith",
  57 + "blocked": false,
  58 + "created_at": "2012-05-23T08:00:58Z",
  59 + "bio": null,
  60 + "skype": "",
  61 + "linkedin": "",
  62 + "twitter": "",
  63 + "dark_scheme": false,
  64 + "theme_id": 1
  65 +}
  66 +```
  67 +
  68 +## Current user
  69 +
  70 +Get currently authenticated user.
  71 +
  72 +```
  73 +GET /user
  74 +```
  75 +
  76 +```json
  77 +{
  78 + "id": 1,
  79 + "email": "john@example.com",
  80 + "name": "John Smith",
  81 + "blocked": false,
  82 + "created_at": "2012-05-23T08:00:58Z",
  83 + "bio": null,
  84 + "skype": "",
  85 + "linkedin": "",
  86 + "twitter": "",
  87 + "dark_scheme": false,
  88 + "theme_id": 1
  89 +}
  90 +```
... ...
lib/api.rb
  Diff comments   View file @bf519f6
... ... @@ -5,6 +5,10 @@ module Gitlab
5 5 VERSION = 'v2'
6 6 version VERSION, :using => :path
7 7  
  8 + rescue_from ActiveRecord::RecordNotFound do
  9 + rack_response({'message' => '404 Not found'}.to_json, 404)
  10 + end
  11 +
8 12 format :json
9 13 error_format :json
10 14 helpers APIHelpers
... ...
lib/api/entities.rb
  Diff comments   View file @bf519f6
... ... @@ -5,9 +5,13 @@ module Gitlab
5 5 :dark_scheme, :theme_id, :blocked, :created_at
6 6 end
7 7  
  8 + class UserBasic < Grape::Entity
  9 + expose :id, :email, :name, :blocked, :created_at
  10 + end
  11 +
8 12 class Project < Grape::Entity
9 13 expose :id, :code, :name, :description, :path, :default_branch
10   - expose :owner, :using => Entities::User
  14 + expose :owner, :using => Entities::UserBasic
11 15 expose :private_flag, :as => :private
12 16 expose :issues_enabled, :merge_requests_enabled, :wall_enabled, :wiki_enabled, :created_at
13 17 end
... ... @@ -22,7 +26,7 @@ module Gitlab
22 26  
23 27 class ProjectSnippet < Grape::Entity
24 28 expose :id, :title, :file_name
25   - expose :author, :using => Entities::User
  29 + expose :author, :using => Entities::UserBasic
26 30 expose :expires_at, :updated_at, :created_at
27 31 end
28 32 end
... ...