Api reference (#12)

Co-authored-by: Borja Muñoz <borjamunoz@carto-bmunoz.local>
Co-authored-by: VictorVelarde <victor.velarde@gmail.com>

docs/api-reference/api.md

@@ -1,63 +1,66 @@
 # API
 
-## Functions
-
-### executeSQL
-
-Executes a SQL query
-
-#### Parameters
-
-##### `credentials` ({ username, apiKey, serverUrlTemplate })
+Functions for working with CARTO REST APIs
 
-Required. CARTO user credentials.
+## Functions
 
-##### `query` (String)
+<dl>
+<dt><a href="#buildQueryFilters">buildQueryFilters</a> ⇒ <code>string</code></dt>
+<dd><p>Returns a SQL query applying a set of filters</p>
+</dd>
+<dt><a href="#executeSQL">executeSQL</a> ⇒ <code>Object</code></dt>
+<dd><p>Execute a SQL query</p>
+</dd>
+<dt><a href="#getUserDatasets">getUserDatasets</a> ⇒ <code>Object</code></dt>
+<dd><p>Get the lists of datasets for the user by performing a request to CARTO datasets API</p>
+</dd>
+</dl>
+
+<a name="buildQueryFilters"></a>
+
+## buildQueryFilters ⇒ <code>string</code>
+Returns a SQL query applying a set of filters
 
-Required. SQL query to be executed.
+**Kind**: global function  
+**Returns**: <code>string</code> - SQL query  
 
-##### `opts` ({ format })
+| Param | Type | Description |
+| --- | --- | --- |
+| data | <code>string</code> | Dataset name or SQL query |
+| filters | <code>Object</code> | Filters to be applied |
 
-Optional. Additional options for the HTTP request.
+<a name="executeSQL"></a>
 
-#### Returns
+## executeSQL ⇒ <code>Object</code>
+Executes a SQL query
 
-{ Object }. Data returned from the SQL query execution.
+**Kind**: global function  
+**Returns**: <code>Object</code> - Data returned from the SQL query execution  
 
-If `opts.format` is "geojson", it returns the full object returned by CARTO SQL API; otherwise it returns only the `rows` property.
+| Param | Type | Description |
+| --- | --- | --- |
+| credentials | <code>Object</code> | CARTO user credentials |
+| credentials.username | <code>string</code> | CARTO username |
+| credentials.apiKey | <code>string</code> | CARTO API Key |
+| credentials.serverUrlTemplate | <code>string</code> | CARTO server URL template |
+| query | <code>string</code> | SQL query to be executed |
+| opts | <code>Object</code> | Additional options for the HTTP request |
+| opts.format | <code>string</code> | Output format (i.e. geojson) |
 
-### getUserDatasets
+<a name="getUserDatasets"></a>
 
+## getUserDatasets ⇒ <code>Object</code>
 Get the lists of datasets for the user by performing a request to CARTO datasets API
 
-#### Parameters
-
-##### `credentials` ({ username, apiKey, serverUrlTemplate })
-
-Required. CARTO user credentials.
-
-##### `opts` ({ Object })
-
-Optional. Additional options for the HTTP request.
-
-#### Returns
-
-{ Object }. List of datasets owned by the user that are in CARTO canonical form (cartodbfied).
-
-### buildQueryFilters
-
-Returns a SQL query applying a set of filters
-
-#### Parameters
-
-##### `data` ({ string }) 
-
-Required. Dataset name or SQL query
-
-##### `filters` ({ Object }) 
-
-Optional. Filters to be applied
+**Kind**: global function  
+**Returns**: <code>Object</code> - List of datasets  
 
-#### Returns
+| Param | Type | Description |
+| --- | --- | --- |
+| credentials | <code>Object</code> | CARTO user credentials |
+| credentials.username | <code>string</code> | CARTO username |
+| credentials.apiKey | <code>string</code> | CARTO API Key |
+| credentials.serverUrlTemplate | <code>string</code> | CARTO server URL template |
+| opts | <code>Object</code> | Additional options for the HTTP request |
+| opts.format | <code>string</code> | Output format (i.e. geojson) |
 
-{ string }. SQL query.

docs/api-reference/basemaps.md

@@ -0,0 +1,40 @@
+# Basemaps
+
+Basemaps constants and Google Maps component
+
+## Constants
+
+<dl>
+<dt><a href="#POSITRON">POSITRON</a> : <code>string</code></dt>
+<dd></dd>
+<dt><a href="#VOYAGER">VOYAGER</a> : <code>string</code></dt>
+<dd></dd>
+<dt><a href="#DARK_MATTER">DARK_MATTER</a> : <code>string</code></dt>
+<dd></dd>
+<dt><a href="#GOOGLE_ROADMAP">GOOGLE_ROADMAP</a> : <code>string</code></dt>
+<dd></dd>
+<dt><a href="#GOOGLE_SATELLITE">GOOGLE_SATELLITE</a> : <code>string</code></dt>
+<dd></dd>
+<dt><a href="#GOOGLE_HYBRID">GOOGLE_HYBRID</a> : <code>string</code></dt>
+<dd></dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#GoogleMap">GoogleMap(props)</a></dt>
+<dd><p>React component for working with Google Maps API and deck.gl</p>
+</dd>
+</dl>
+
+**Kind**: global function  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| props | <code>Object</code> | Properties |
+| props.basemap | <code>Object</code> | Basemap (see basemaps constants) |
+| props.viewState | <code>Object</code> | Viewstate (center, zoom level) |
+| props.layers | <code>Array.&lt;Layer&gt;</code> | Layers array |
+| props.getTooltip | <code>function</code> | Tooltip handler |
+| props.apiKey | <code>string</code> | Google Maps API Key |
+

docs/api-reference/oauth.md

@@ -0,0 +1,51 @@
+# OAuth
+
+OAuth functions and hook
+
+<dl>
+<dt><a href="#module_OAuthCallback">OAuthCallback</a></dt>
+<dd><p>Component to attend OAuth callbacks on /oauthCallback</p>
+</dd>
+<dt><a href="#module_OAuthLogin">OAuthLogin</a></dt>
+<dd><p>Shows a login button.
+When this button is clicked, the OAuth protocol flow is handled
+by the <code>useOAuthLogin</code> hook.</p>
+</dd>
+<dt><a href="#module_useOAuthLogin">useOAuthLogin</a> ⇒ <code>function</code></dt>
+<dd><p>Hook to perform login against CARTO using OAuth implicit flow using a popup</p>
+</dd>
+</dl>
+
+<a name="module_OAuthCallback"></a>
+
+## OAuthCallback
+Component to attend OAuth callbacks on /oauthCallback
+
+**Kind**: global function  
+
+<a name="module_OAuthLogin"></a>
+
+## OAuthLogin
+Shows a login button.
+When this button is clicked, the OAuth protocol flow is handled
+by the `useOAuthLogin` hook.
+
+**Kind**: global function  
+
+<a name="module_useOAuthLogin"></a>
+
+## useOAuthLogin ⇒ <code>function</code>
+Hook to perform login against CARTO using OAuth implicit flow using a popup
+
+**Kind**: global function  
+**Returns**: <code>function</code> - Function to trigger oauth with a popup  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| oauthApp | <code>Object</code> | OAuth parameters |
+| oauthApp.clientId | <code>string</code> | Application client ID |
+| oauthApp.scopes | <code>Array.&lt;string&gt;</code> | Scopes to request |
+| oauthApp.authorizeEndPoint | <code>string</code> | Authorization endpoint |
+| onParamsRefreshed | <code>function</code> | Function to call when params are refreshed |
+
+

src/api/SQL.js

@@ -6,11 +6,15 @@ import { dealWithApiError, generateApiUrl } from './common';
 const API = 'api/v2/sql';
 
 /**
- * Execute a SQL query
+ * Executes a SQL query
  *
- * @param { username, apiKey, serverUrlTemplate } credentials - CARTO user credentials
+ * @param { Object } credentials - CARTO user credentials
+ * @param { string } credentials.username - CARTO username
+ * @param { string } credentials.apiKey - CARTO API Key
+ * @param { string } credentials.serverUrlTemplate - CARTO server URL template
  * @param { string } query - SQL query to be executed
- * @param { format } opts - Additional options for the HTTP request
+ * @param { Object } opts - Additional options for the HTTP request
+ * @param { string } opts.format - Output format (i.e. geojson)
  * @returns { Object } - Data returned from the SQL query execution
  */
 export const executeSQL = async (credentials, query, opts = {}) => {

src/api/UserDatasets.js

@@ -6,8 +6,12 @@ const API = 'api/v4/datasets';
 /**
  * Get the lists of datasets for the user by performing a request to CARTO datasets API
  *
- * @param { username, apiKey, serverUrlTemplate } credentials - CARTO user credentials
+ * @param { Object } credentials - CARTO user credentials
+ * @param { string } credentials.username - CARTO username
+ * @param { string } credentials.apiKey - CARTO API Key
+ * @param { string } credentials.serverUrlTemplate - CARTO server URL template
  * @param { Object } opts - Additional options for the HTTP request
+ * @param { string } opts.format - Output format (i.e. geojson)
  * @returns { Object } - List of datasets
  */
 export const getUserDatasets = async (credentials, opts = {}) => {

src/basemaps/GoogleMap.js

@@ -2,6 +2,17 @@ import React, { useEffect, useRef } from 'react';
 import { GoogleMapsOverlay } from '@deck.gl/google-maps';
 import { debounce } from '../utils';
 
+/**
+ * React component for working with Google Maps API and deck.gl
+ *
+ * @param { Object } props - Properties
+ * @param { Object } props.basemap - CARTO username
+ * @param { Object } props.viewState - Viewstate (center, zoom level)
+ * @param { Layer[] } props.layers - Layers array
+ * @param { function } props.getTooltip - Tooltip handler
+ * @param { string } props.apiKey - Google Maps API Key
+ * @returns { Object } - Data returned from the SQL query execution
+ */
 export function GoogleMap(props) {
   const { basemap, viewState, layers, getTooltip, apiKey } = props;
   // based on https://publiuslogic.com/blog/google-maps+react-hooks/

src/basemaps/basemaps.js

@@ -1,8 +1,36 @@
+/** @constant
+    @type {string}
+    @default
+*/
 export const POSITRON = 'positron';
+/** @constant
+    @type {string}
+    @default
+*/
 export const VOYAGER = 'voyager';
+/** @constant
+    @type {string}
+    @default
+*/
+/** @constant
+    @type {string}
+    @default
+*/
 export const DARK_MATTER = 'dark-matter';
+/** @constant
+    @type {string}
+    @default
+*/
 export const GOOGLE_ROADMAP = 'roadmap';
+/** @constant
+    @type {string}
+    @default
+*/
 export const GOOGLE_SATELLITE = 'satellite';
+/** @constant
+    @type {string}
+    @default
+*/
 export const GOOGLE_HYBRID = 'hybrid';
 
 export const BASEMAPS = {

src/oauth/OAuthCallback.js

@@ -1,5 +1,6 @@
 /**
  * Component to attend OAuth callbacks on /oauthCallback
+ * @exports OAuthCallback
  */
 export default function OAuthCallback() {
   return null;

src/oauth/OAuthLogin.js

@@ -11,6 +11,13 @@ const useStyles = makeStyles(() => ({
   },
 }));
 
+/** 
+ * Shows a login button.
+ * When this button is clicked, the OAuth protocol flow is handled
+ * by the `useOAuthLogin` hook.
+ * 
+ * @exports OAuthLogin
+ */
 export default function OAuthLogin() {
   const dispatch = useDispatch();
   const classes = useStyles();

src/oauth/useOAuthLogin.js

@@ -4,8 +4,13 @@ import { createOAuthPopup, getOAuthParamsFromCallback } from './oauthHelper';
 /**
  * Hook to perform login against CARTO using OAuth implicit flow using a popup
  *
- * @param { clientId, scopes, authorizeEndPoint } oauthApp data
- * @returns [handleLogin] - function to trigger oauth with a popup
+ * @param { Object } oauthApp - OAuth parameters
+ * @param { string } oauthApp.clientId - Application client ID
+ * @param { string[] } oauthApp.scopes - Scopes to request
+ * @param { string } oauthApp.authorizeEndPoint - Authorization endpoint
+ * @param { function } onParamsRefreshed - Function to call when params are refreshed
+ * @returns { function } - Function to trigger oauth with a popup
+ * @exports useOAuthLogin
  */
 export default function useOAuthLogin(oauthApp, onParamsRefreshed) {
   const [oauthParams, setOAuthParams] = useState(null);