Edits to API files

This commit is contained in:
Ro 2021-07-05 12:26:56 -07:00
commit 7d80e42642
4 changed files with 253 additions and 107 deletions

File diff suppressed because one or more lines are too long

3
src/jsdoc.json Normal file
View file

@ -0,0 +1,3 @@
{
"plugins": ["plugins/markdown"]
}

View file

@ -27,12 +27,14 @@ export const TASK_PAGE_EDIT = "editPage";
export const TASK_PAGE_DELETE = "deletePage"; export const TASK_PAGE_DELETE = "deletePage";
export const TASK_SEND_MAIL = "sendMail"; export const TASK_SEND_MAIL = "sendMail";
export const TASK_REINDEX_PAGE = "reIndexPages"; export const TASK_REINDEX_PAGE = "reIndexPages";
export const TASK_SYNC_SETTNIGS = "syncSite";
export const TASK_SYNC_NAV = "syncNav";
//** API STATUS **// //** API STATUS **//
export const API_ACCESS_GOOD = "apiUseAuthorized"; export const API_ACCESS_GOOD = "apiUseAuthorized";
export const API_ACCESS_BAD = "apiUseNotAuthorized"; export const API_ACCESS_BAD = "apiUseNotAuthorized";
/** /**
* A can of methods used to edit install settings, navigation pages. * A can of methods used to edit install settings, navigation pages and content pages
*/ */
class FipamoAdminAPI { class FipamoAdminAPI {
@ -63,10 +65,22 @@ class FipamoAdminAPI {
}); });
} }
/** /**
* Promise method for checking credentials. Must login to use Admin API. * Promise method for authenticating and starting a session\
* @param {object} data - json object that contains data for set up * **POST**`/api/v1/login`
* @property {string} handle - handle for site user * @param {Object[]} data - json object that contains data for set up
* @property {string} password - password for site user * @param {string} data[].handle - handle for site user
* @param {string} data[].password - password for site user
* @example
* api.login(data).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of login request
```
{
"message":"Example Message of Affirmation or what you're missing!",
"type":"exampleType",
}
```
*/ */
login(data) { login(data) {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
@ -88,31 +102,59 @@ class FipamoAdminAPI {
}); });
} }
/** /**
* Method for saving settings * Method for saving site and navigation settings\
* @param {object} data - json object that contains settings data set on the front-end * **POST**`/api/v1/settings/:task`
* @property {string} global.base_url - base url for site * @param {string} task - settings being synced `config | navigation`
* @property {string} global.title - site title * @param {object[]} data - json object that contains settings data for [site] or [nav]
* @property {string} global.descriptions - brief site summary * @param {string} data[].global.base_url - base url for site [site]
* @property {string} global.background - url for site feature image for header * @param {string} data[].global.title - site title [site]
* @property {boolean} global.private - privacy state for site [disabled] * @param {string} data[].global.descriptions - brief site summary [site]
* @property {boolean} global.renderOnSave - property for publishing site when page saved [disabled] * @param {string} data[].global.background - url for site feature image for header [site]
* @property {string} global.theme - current theme for site * @param {boolean} data[].global.private - privacy state for site [disabled] [site]
* @property {boolean} global.externalAPI - toggle for external API access * @param {boolean} data[].global.renderOnSave - property for publishing site when page saved [disabled] [site]
* @property {string} member.handle - current member handle * @param {string} data[].global.theme - current theme for site [site]
* @property {string} member.email - current member email * @param {boolean} data[].global.externalAPI - toggle for external API access [site]
* @property {string} email.active - current email protocol being used * @param {string} data[].member.handle - current member handle [site]
* @property {string} email.smtp.domain - url of smtp service being * @param {string} data[].member.email - current member email [site]
* @property {string} email.smtp.email - email account of smtp service * @param {string} data[].email.active - current email protocol being used [site]
* @property {string} email.smtp.password - password for email of smtp service * @param {string} data[].email.smtp.domain - url of smtp service being [site]
* @property {string} email.mailgun.domain - mailgun domain url * @param {string} data[].email.smtp.email - email account of smtp service [site]
* @property {string} email.mailgun.key - mailgun key * @param {string} data[].email.smtp.password - password for email of smtp service [site]
* @param {string} data[].email.mailgun.domain - mailgun domain url [site]
* @param {string} data[].email.mailgun.key - mailgun key [site]
*
* @param {string} data[].item.title - page title [nav]
* @param {string} data[].item.slug - url safe title [nav]
* @param {string} data[].item.uuid - unique identifier [nav]
* @param {string} data[].item.path - directory path to associated markdown file [nav]
* @example
* api.sync(TASK, data).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of sync request
```
*
{
"message":"Example Message of Affirmation!",
"type":"exampleType",
}
```
*/ */
syncSettings(data) { sync(task, data) {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
let url = "";
switch (task) {
case "syncSite":
url = API_SETTINGS_SYNC;
break;
case "syncNav":
url = API_NAV_SYNC;
break;
}
this._request( this._request(
this.baseURL this.baseURL
? this.baseURL + API_SETTINGS_SYNC + "?key=" + this.key ? this.baseURL + url + "?key=" + this.key
: API_SETTINGS_SYNC + "?key=" + this.key, : url + "?key=" + this.key,
TASK_SETTINGS_WRITE, TASK_SETTINGS_WRITE,
REQUEST_TYPE_POST, REQUEST_TYPE_POST,
CONTENT_TYPE_JSON, CONTENT_TYPE_JSON,
@ -129,10 +171,21 @@ class FipamoAdminAPI {
/** /**
* Method for retrieving user authorizing user login * Method for retrieving user authorizing user login
* @param {object} data - json object that contains task * @param {object[]} data - json object that contains task
* @property {string} task - publishing task [deprecated] * @param {string} data[].task - publishing task
* @example
* api.publish(TASK).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of publis request
* ```
{
"message":"Example Message of Affirmation!",
"type":"exampleType",
}
* ```
*/ */
publishSite(data) { publish(data) {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
this._request( this._request(
//API_PUBLISH_PAGES, //API_PUBLISH_PAGES,
@ -152,22 +205,34 @@ class FipamoAdminAPI {
} }
/** /**
* Method for handling page creating and editing * Method for handling page creating and editing\
* **POST**`/api/v1/page/:task`
* @param {string} task - current page action * @param {string} task - current page action
* @param {object} data - form object that contains info for current page being edited/created * @param {object[]} form - form object that contains info for current page being edited/created
* @property {string} id - sequence id for page * @param {string} form[].id - sequence id for page, leave empty for new page
* @property {string} uuid - unique identifier for page * @param {string} form[].uuid - unique identifier for page, leave empty for new page
* @property {string} layout - current page layout * @param {string} form[].layout - current page layout
* @property {string} current_title - saved url save title for persistence when changing title * @param {string} form[].current_title - saved url save title for persistence when changing title, leave empty for new page
* @property {string} content - markdown body of page * @param {string} form[].content - markdown body of page
* @property {string} title - current title of page * @param {string} form[].title - current title of page
* @property {string} created - date page was created * @param {string} form[].created - date page was created, leave empty for new page
* @property {string} slug - url safe string of page title * @param {string} form[].slug - url safe string of page title
* @property {string} tags - comma separated list of tags * @param {string} form[].tags - comma separated list of tags
* @property {boolean} menu - property that indicates page is included in site menu * @param {boolean} form[].menu - property that indicates page is included in site menu
* @property {boolean} featured - property that indicates page is featured * @param {boolean} form[].featured - property that indicates page is featured
* @property {boolean} published - property that indicates page is public * @param {boolean} form[].published - property that indicates page is public
* @property {input} feature_image - main image for page * @param {input} form[].feature_image - main image for page
* @example
* api.pageActions(TASK, data).then(response=>{
* console.log("RESPONSE", response);
* })
* @returns {object} json object that contains type and status of page edit request
```
{
"message":"Example Message of Affirmation!",
"type":"exampleType",
}
```
*/ */
pageActions(task, data) { pageActions(task, data) {
let url, event, content; let url, event, content;
@ -218,34 +283,21 @@ class FipamoAdminAPI {
} }
/** /**
* Method for saving pages to be included in main site navigation * Method for sending mail (if completed in settings)\
* @param {object} data - json object that contains items to be included in main site navigation * **POST**`/api/v1/mailer`
* @property {string} item.title - page title * @param {object[]} message - json object that contains items to be included in main site navigation
* @property {string} item.slug - url safe title * @param {string} message[].content - message to send
* @property {string} item.uuid - unique identifier * @example
* @property {string} item.path - directory path to associated markdown file * api.sendMail(message).then(response=>{
*/ * console.log("RESPONSE", response);
syncNav(data) { * })
return new Promise((resolve, reject) => { * @returns {object} json object that contains type and status of page edit request
this._request( ```
this.baseURL ? this.baseURL + API_NAV_SYNC : API_NAV_SYNC, {
TASK_SETTINGS_WRITE, "message":"Example Message of Affirmation!",
REQUEST_TYPE_POST, "type":"exampleType"
CONTENT_TYPE_JSON,
data
)
.then((result) => {
resolve(result);
})
.catch((err) => {
reject(err);
});
});
} }
/** ```
* Method for sending mail
* @param {object} message - json object that contains items to be included in main site navigation
* @property {string} content - message to send
*/ */
sendMail(message) { sendMail(message) {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
@ -264,27 +316,7 @@ class FipamoAdminAPI {
}); });
}); });
} }
/**
* Maintenance method to clean up page sequencing [disabled]
* @param {object} data - json object that contains items to be included in main site navigation
*/
reindexPages(data) {
return new Promise((resolve, reject) => {
this._request(
this.baseURL ? this.baseURL + API_REINDEX_PAGES : API_REINDEX_PAGES,
TASK_REINDEX_PAGE,
REQUEST_TYPE_POST,
CONTENT_TYPE_JSON,
data
)
.then((result) => {
resolve(result);
})
.catch((err) => {
reject(err);
});
});
}
//-------------------------- //--------------------------
// private // private
//-------------------------- //--------------------------

View file

@ -19,15 +19,13 @@ export const API_GET_TAGS = "/api/v1/page/tags";
export const TASK_GET_CONTENT = "retrieveContent"; export const TASK_GET_CONTENT = "retrieveContent";
/** /**
* Fipamo Content API * A bag of methods for getting content from an install.
* A bag of methods for getting page info from an install.
* To use remotely, include url of install and user key found in settings in the Dashboard.
*/ */
class FipamoContentAPI { class FipamoContentAPI {
/** /**
* @constructor * @constructor
* @param {string} baseURL - url of site; uses local when empty * @param {string} baseURL - url of install, defaults to local
* @param {string} key - user api key * @param {string} key - user api key found in Settings
* @author Ro * @author Ro
*/ */
constructor(baseURL = null, key = null) { constructor(baseURL = null, key = null) {
@ -38,14 +36,61 @@ class FipamoContentAPI {
} }
/** /**
* Promise method for retrieving page data * *Promise method for retrieving page data*\
* @param {string} type - type of pages being retrieved; null value defaults to published * **GET**`/api/v1/page/:type`
* @param {string} type - type of pages (`published | menu | featured`) being retrieved; null value defaults to `published`
* @example * @example
* api.pages('published').then(pages=>{ * api.pages('published').then(pages=>{
* console.log("Pages Object", pages); * console.log("Pages Object", pages);
* }) * })
* @returns {object} json object that contains pages of requested type * @returns {object} json object that contains pages of requested type
* *
* *pages object example*
* ```
{
"pages":
[
{
"id":1,
"uuid":"uuid-for-entry",
"title":"Entry Title",
"feature":"/path/to/image.jpg",
"path":"2020/09",
"layout":"page",
"tags":"these, are, tags",
"author":"your-name",
"created":"2020 Sep Tue 01",
"updated":"2020 Sep Tue 01",
"deleted":false,
"menu":false,
"featured":false,
"published":true,
"slug":"entry-title",
"content":"Premium Content"
},
{
"id":2,
"uuid":"uuid-for-entry",
"title":"Another Title",
"feature":"/path/to/image.jpg",
"path":"2020/09",
"layout":"page",
"tags":"these, are, tags",
"author":"your-name",
"created":"2020 Sep Tue 01",
"updated":"2020 Sep Tue 01",
"deleted":false,
"menu":false,
"featured":false,
"published":true,
"slug":"another-title",
"content":"Premium Content"
}
],
"totalItems":2
}
* ```
*
*/ */
pages(type = null) { pages(type = null) {
//set url based on request type //set url based on request type
@ -76,13 +121,36 @@ class FipamoContentAPI {
}); });
} }
/** /**
* Promise method for retrieving single page * *Promise method for retrieving single page*\
* **GET** `/api/v1/page/single/:id`
* @param {string} id - uuid of desired page * @param {string} id - uuid of desired page
* @example * @example
* api.page("a-uuid-for-a-page").then(page=>{ * api.page("a-uuid-for-a-page").then(page=>{
console.log("Page Object", page); console.log("Page Object", page);
* }) * })
* @returns {object} json object that contains data for requested page * @returns {object} json object that contains data for requested page
*
* *page object example*
* ```
{
"id":1,
"uuid":"uuid-for-entry",
"title":"Entry Title",
"feature":"/path/to/image.jpg",
"path":"2020/09",
"layout":"page",
"tags":"these, are, tags",
"author":"your-name",
"created":"2020 Sep Tue 01",
"updated":"2020 Sep Tue 01",
"deleted":false,
"menu":false,
"featured":false,
"published":true,
"slug":"entry-title",
"content":"Premium Content"
}
* ```
*/ */
page(id) { page(id) {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
@ -103,12 +171,55 @@ class FipamoContentAPI {
} }
/** /**
* Promise method for retrieving all tags used by pages * *Promise method for retrieving all tags used by pages*\
* **GET** `/api/v1/page/tags`
* @example * @example
* api.tags().then(tags=>{ * api.tags().then(tags=>{
console.log("Tags Object", tags); console.log("Tags Object", tags);
* }) * })
* @returns {object} json object that contains tags used by pages * @returns {object} json object that contains site tags and page stubs associated with said tag
*
* *tags object example*
* ```
[
{
"tag_name":"this is a tag",
"slug":"this-is-a-tag",
"pages":
[
{
"title":"This is a title",
"slug":"this-is-a-title",
"path":"2021/04"
},
{
"title":"This is another title",
"slug":"this-is-another-title",
"path":"2020/10"
}
]
},
{
"tag_name":"this is another tag",
"slug":"this-is-another-tag",
"pages":
[
{
"title":"This is a title",
"slug":"this-is-a-title",
"path":"2021/04"
},
{
"title":"This is another title",
"slug":"this-is-another-title",
"path":"2020/10"
}
]
}
]
* ```
*/ */
tags() { tags() {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {