Skip to content

GitLab

Application Programming Interface
Application Programming Interface
Commit b3110c3a authored by zauberstuhl's avatar zauberstuhl
Browse files
Options

Add apidoc documentation to controllers

parent 42687d75
Hide whitespace changes
Inline Side-by-side
Showing with 689 additions and 9 deletions
.gitignore
View file @ b3110c3a
docs/
package-lock.json
README.md
View file @ b3110c3a
GangGo Restful API Library
--------------------------
# GangGo API Library
## Documentation
If you want to write an application for GangGo checkout our [API documentation page](https://ganggo.github.io/api/index.html).
### Generate
Download and install apidoc via:
npm install apidoc -g
Then run in the api repository:
apidoc -i app -o <docs-path>
apidoc.json
View file @ b3110c3a
......@@ -3,5 +3,11 @@
"version": "0.0.0",
"description": "GangGo API Library",
"title": "API Documentation",
"url" : "/api/v0"
"url": "/api/v0",
"header": {
"filename": "docs/header.md"
},
"footer": {
"filename": "docs/footer.md"
}
}
app/controllers/aspect.go
View file @ b3110c3a
......@@ -24,12 +24,56 @@ import (
"errors"
)
/**
* @apiDefine Aspects Aspects endpoint
*
* Viewing, creating and deleting Aspect structures
*/
type ApiAspect struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /people/:id/aspects Display aspects which Person is included in
* @apiName ApiAspect.ShowPerson
* @apiGroup Aspects
*
* @apiParam {Number} id Person database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Name Aspect name
* @apiSuccess {Number} UserID User database ID
* @apiSuccess {Boolean} Default Default aspect
* @apiSuccess {Array} Memberships Aspect memberships
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "Name": "Friends",
* "UserID": 1,
* "Default": false,
* "Memberships": [...]
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) ShowPerson() revel.Result {
var (
personID uint
......@@ -52,6 +96,41 @@ func (a ApiAspect) ShowPerson() revel.Result {
return a.RenderJSON(aspects)
}
/**
* @api {post} /people/:id/aspects/:aspect_id Add person to aspect
* @apiName ApiAspect.CreatePerson
* @apiGroup Aspects
*
* @apiParam {Number} id Person database ID
* @apiParam {Number} aspect_id Aspect database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Number} AspectID Aspect database ID
* @apiSuccess {Number} PersonID Person database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "AspectID": 1,
* "PersonID": 1
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) CreatePerson() revel.Result {
var personID, aspectID uint
......@@ -72,6 +151,41 @@ func (a ApiAspect) CreatePerson() revel.Result {
return a.RenderJSON(membership)
}
/**
* @api {delete} /people/:id/aspects/:aspect_id Delete person from aspect
* @apiName ApiAspect.DeletePerson
* @apiGroup Aspects
*
* @apiParam {Number} id Person database ID
* @apiParam {Number} aspect_id Aspect database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Number} AspectID Aspect database ID
* @apiSuccess {Number} PersonID Person database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "AspectID": 1,
* "PersonID": 1
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) DeletePerson() revel.Result {
var personID, aspectID uint
......@@ -103,6 +217,43 @@ func (a ApiAspect) Index(fields string) revel.Result {
helpers.SelectStructFields(user.Aspects, fields))
}
/**
* @api {post} /aspects Create new aspect
* @apiName ApiAspect.Create
* @apiGroup Aspects
*
* @apiParam {String} aspect_name Aspect name
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Name Aspect name
* @apiSuccess {Number} UserID User database ID
* @apiSuccess {Boolean} Default Default aspect
* @apiSuccess {Array} Memberships Aspect memberships
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 1,
* "CreatedAt": "2017-12-20T00:02:10Z",
* "UpdatedAt": "2017-12-20T00:02:10Z",
* "Name": "Friends",
* "UserID": 1,
* "Default": false,
* "Memberships": [...]
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (a ApiAspect) Create() revel.Result {
name := a.Params.Get("aspect_name")
if name == "" {
......
app/controllers/comment.go
View file @ b3110c3a
......@@ -24,12 +24,61 @@ import (
federation "gopkg.in/ganggo/federation.v0"
)
/**
* @apiDefine Comments Comments endpoint
*
* Viewing, creating and deleting Comment structures
*/
type ApiComment struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /posts/:id/comments Display comments related to post
* @apiName ApiComment.Index
* @apiGroup Comments
*
* @apiParam {Number} id Post database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Text Status message
* @apiSuccess {Number} ShareableID Post database ID
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {String} ShareableType Shareable type e.g. Post, Comment
* @apiSuccess {Hash} CommentSignature Signature
* @apiSuccess {Hash} Person Person structure
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "Text": "hi",
* "ShareableID": 20,
* "PersonID": 1,
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "LikesCount": 0,
* "ShareableType": "Post",
* [...]
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (c ApiComment) Index() revel.Result {
var (
postID uint
......@@ -45,6 +94,24 @@ func (c ApiComment) Index() revel.Result {
return c.RenderJSON(comments)
}
/**
* @api {post} /posts/:id/comments Create comment on post
* @apiName ApiComment.Create
* @apiGroup Comments
*
* @apiParam {Number} id Post database ID
* @apiParam {String} comment Status message
* @apiParam {String} [fields] Display only specific fields, e.g. fields=ID,Person(ID:Profile(ID:ImageUrl))
* @apiParam {String} access_token Oauth access token
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (c ApiComment) Create() revel.Result {
var (
comment, fields string
......
app/controllers/like.go
View file @ b3110c3a
......@@ -25,12 +25,60 @@ import (
federation "gopkg.in/ganggo/federation.v0"
)
/**
* @apiDefine Likes Likes endpoint
*
* Viewing, creating and deleting Like structures
*/
type ApiLike struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /posts/:id/likes Display likes related to post
* @apiName ApiLike.Index
* @apiGroup Likes
*
* @apiParam {Number} id Post database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Positive Like or dis-like
* @apiSuccess {Number} TargetID Post database ID
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {String} AuthorSignature Signature
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Hash} Signature Signature structure
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetID": 20,
* "PersonID": 1,
* "Positive": true,
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "TargetType": "Post",
* [...]
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (l ApiLike) Index() revel.Result {
var (
postID uint
......@@ -47,6 +95,48 @@ func (l ApiLike) Index() revel.Result {
return l.RenderJSON(likes)
}
/**
* @api {post} /posts/:id/likes Create a like
* @apiName ApiLike.Create
* @apiGroup Likes
*
* @apiParam {Number} id Post database ID
* @apiParam {Boolean} positive Like or dis-like
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {String} Guid Unique global ID
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Positive Like or dis-like
* @apiSuccess {Number} TargetID Post database ID
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {String} AuthorSignature Signature
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Hash} Signature Signature structure
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetID": 20,
* "PersonID": 1,
* "Positive": true,
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "TargetType": "Post",
* [...]
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (l ApiLike) Create() revel.Result {
var (
postID uint
......
app/controllers/notification.go
View file @ b3110c3a
......@@ -22,12 +22,56 @@ import (
"gopkg.in/ganggo/ganggo.v0/app/models"
)
/**
* @apiDefine Notifications Notifications endpoint
*
* Viewing, creating and deleting Notification structures
*/
type ApiNotification struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /notifications Display notifications
* @apiName ApiNotification.Index
* @apiGroup Notifications
*
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Unread If the notification is un-read
* @apiSuccess {String} TargetGuid Entity global ID
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {Number} UserID User database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetGuid": "cc783a9749f09c7d817a1707a4c052bc",
* "PersonID": 1,
* "UserID": 2,
* "Unread": true,
* "TargetType": "Post"
* }
* ]
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (n ApiNotification) Index() revel.Result {
user, err := models.CurrentUser(n.Params, n.Session)
if err != nil {
......@@ -53,6 +97,44 @@ func (n ApiNotification) Show() revel.Result {
return n.NotFound("Not implemented yet")
}
/**
* @api {put} /notifications/:id Set notification read
* @apiName ApiNotification.Update
* @apiGroup Notifications
*
* @apiParam {Number} id Notification database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {Boolean} Unread If the notification is un-read
* @apiSuccess {String} TargetGuid Entity global ID
* @apiSuccess {String} TargetType Entity type e.g. Post, Comment
* @apiSuccess {Number} PersonID Person database ID
* @apiSuccess {Number} UserID User database ID
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "TargetGuid": "cc783a9749f09c7d817a1707a4c052bc",
* "PersonID": 1,
* "UserID": 2,
* "Unread": false,
* "TargetType": "Post"
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (n ApiNotification) Update(id uint) revel.Result {
user, err := models.CurrentUser(n.Params, n.Session)
if err != nil {
......
app/controllers/oauth.go
View file @ b3110c3a
......@@ -32,15 +32,41 @@ type TokenResult struct {
// it checks on interface nil value
type TokenString string
/**
* @apiDefine Oauth Oauth endpoint
*
* Create and delete oauth tokens
*/
type ApiOAuth struct {
*revel.Controller
}
// Basic password credentials flow
// /token?grant_type=password&username=USERNAME&password=PASSWORD&client_id=CLIENT_ID
//
// If the password and username are correct
// the application is authorized and it will return an access token
/**
* @api {post} /oauth/tokens Create/Fetch token
* @apiName ApiOAuth.Create
* @apiGroup Oauth
*
* @apiParam {String} grant_type Grant type
* @apiParam {String} username Username
* @apiParam {String} password Password
* @apiParam {String} client_id Client name e.g. android_appXYZ
*
* @apiSuccess {String} token Access token
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "token": "5b5d5b4f7044e3444db73504e8b08be8"
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (o ApiOAuth) Create() revel.Result {
var (
grantType string
......@@ -113,6 +139,27 @@ func (o ApiOAuth) Create() revel.Result {
})
}
/**
* @api {delete} /oauth/tokens/:id Delete token
* @apiName ApiOAuth.Delete
* @apiGroup Oauth
*
* @apiParam {Number} id Token database ID
*
* @apiSuccess {String} token Access token
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {}
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (o ApiOAuth) Delete(id uint) revel.Result {
token := models.OAuthToken{ID: id}
user, err := models.CurrentUser(o.Params, o.Session)
......
app/controllers/people.go
View file @ b3110c3a
......@@ -22,6 +22,11 @@ import (
"gopkg.in/ganggo/ganggo.v0/app/models"
)
/**
* @apiDefine People People endpoint
*
* Viewing, creating and deleting Person structures
*/
type ApiPeople struct {
*revel.Controller
......@@ -36,6 +41,42 @@ func (p ApiPeople) Create() revel.Result {
return p.NotFound("Not implemented yet")
}
/**
* @api {get} /people/:id Display a specific person
* @apiName ApiPeople.Show
* @apiGroup People
*
* @apiParam {String} id Person database ID
* @apiParam {String} access_token Oauth access token
*
* @apiSuccess {String} CreatedAt Timestamp of creation
* @apiSuccess {String} UpdatedAt Timestamp of last replacment
* @apiSuccess {Number} ID Unique database ID
* @apiSuccess {String} Guid Person global ID
* @apiSuccess {String} Author Handle with TLD
* @apiSuccess {String} SerializedPublicKey Public key
* @apiSuccess {Number} UserID User database ID (null if not a local user)
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "ID": 12,
* "CreatedAt": "2018-01-08T15:25:43Z",
* "UpdatedAt": "2018-01-08T15:25:43Z",
* "Guid": "cc783a9749f09c7d817a1707a4c052bc",
* "Author": "test@localhost",
* "SerializedPublicKey": "[...]",
* "UserID": 1,
* }
*
* @apiError error Contains recent error message
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "Error 1052: Column 'xyz' not found"
* }
*/
func (p ApiPeople) Show() revel.Result {
var (
personID uint
......
app/controllers/post.go
View file @ b3110c3a
......@@ -30,12 +30,57 @@ import (
federation "gopkg.in/ganggo/federation.v0"
)
/**
* @apiDefine Posts Posts endpoint
*
* Viewing, creating and deleting Post structures
*/
type ApiPost struct {
*revel.Controller
ApiHelper
}
/**
* @api {get} /posts Fetch all posts
* @apiName ApiPost.Index
* @apiGroup Posts
*
* @apiParam {String} access_token Oauth access token
* @apiParam {Number} [offset] Post offset for database
* @apiParam {String} [fields] Display only specific fields, e.g. fields=ID,Person(ID:Profile(ID:ImageUrl))
* @apiParam {Number} [visibility] 0 = all posts, 1 = public posts, 2 private posts
*