Merge pull request #1043 from NARKOZ/api

API docs

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)

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
+
+Delete 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.

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
+}
+```

lib/api.rb

@@ -5,6 +5,10 @@ module Gitlab
     VERSION = 'v2'
     version VERSION, :using => :path
 
+    rescue_from ActiveRecord::RecordNotFound do
+      rack_response({'message' => '404 Not found'}.to_json, 404)
+    end
+
     format :json
     error_format :json
     helpers APIHelpers

lib/api/entities.rb

@@ -5,9 +5,13 @@ module Gitlab
              :dark_scheme, :theme_id, :blocked, :created_at
     end
 
+    class UserBasic < Grape::Entity
+      expose :id, :email, :name, :blocked, :created_at
+    end
+
     class Project < Grape::Entity
       expose :id, :code, :name, :description, :path, :default_branch
-      expose :owner, :using => Entities::User
+      expose :owner, :using => Entities::UserBasic
       expose :private_flag, :as => :private
       expose :issues_enabled, :merge_requests_enabled, :wall_enabled, :wiki_enabled, :created_at
     end
@@ -22,7 +26,7 @@ module Gitlab
 
     class ProjectSnippet < Grape::Entity
       expose :id, :title, :file_name
-      expose :author, :using => Entities::User
+      expose :author, :using => Entities::UserBasic
       expose :expires_at, :updated_at, :created_at
     end
   end