Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in / Register
Toggle navigation
Application Programming Interface
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Locked Files
Issues
1
Issues
1
List
Boards
Labels
Service Desk
Milestones
Merge Requests
1
Merge Requests
1
Requirements
Requirements
List
Security & Compliance
Security & Compliance
Dependency List
License Compliance
Packages & Registries
Packages & Registries
Container Registry
Analytics
Analytics
Code Review
Insights
Issue
Repository
Value Stream
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
ganggo
Application Programming Interface
Commits
b3110c3a
Commit
b3110c3a
authored
Jan 09, 2018
by
zauberstuhl
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Add apidoc documentation to controllers
parent
42687d75
Changes
13
Hide whitespace changes
Inline
Side-by-side
Showing
13 changed files
with
689 additions
and
9 deletions
+689
-9
.gitignore
.gitignore
+0
-1
README.md
README.md
+15
-2
apidoc.json
apidoc.json
+7
-1
app/controllers/aspect.go
app/controllers/aspect.go
+151
-0
app/controllers/comment.go
app/controllers/comment.go
+67
-0
app/controllers/like.go
app/controllers/like.go
+90
-0
app/controllers/notification.go
app/controllers/notification.go
+82
-0
app/controllers/oauth.go
app/controllers/oauth.go
+52
-5
app/controllers/people.go
app/controllers/people.go
+41
-0
app/controllers/post.go
app/controllers/post.go
+122
-0
app/controllers/profile.go
app/controllers/profile.go
+61
-0
docs/footer.md
docs/footer.md
+0
-0
docs/header.md
docs/header.md
+1
-0
No files found.
.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
*