Add SQLBI licensing docs, improve code syntax

sql-bi · Apr 20, 2024 · 30d8a51 · 30d8a51
1 parent dc3993f
commit 30d8a51
Show file tree

Hide file tree

Showing 35 changed files with 815 additions and 43 deletions.
diff --git a/_myassets/_sass/_theme.scss b/_myassets/_sass/_theme.scss
@@ -9,17 +9,6 @@
     --accent-hover-back-color: #fae8e8;
     --accent-border-color: #8f3838;
     --accent-contrast-color: #fff;
-
-    // DAX Syntax
-    --code-comment-color: #39A03B;
-    --code-string-color: #D93124;
-    --code-column-color: #333;
-    --code-function-color: #035ACA;
-    --code-keyword-color: #035ACA;
-    --code-measure-color: #333;
-    --code-operator-color: #333;
-    --code-number-color: #EE7F18;
-    --code-parenthesis-color: #808080;
 }
 
 // Dark colors
@@ -31,15 +20,4 @@
     --accent-hover-back-color: #fae8e8;
     --accent-border-color: #8f3838;
     --accent-contrast-color: #fff;
-
-    // DAX Syntax
-    --code-comment-color: #86C573;
-    --code-string-color: #E44;
-    --code-column-color: #fff;
-    --code-function-color: #0095ff;
-    --code-keyword-color: #0095ff;
-    --code-measure-color: #fff;
-    --code-operator-color: #fff;
-    --code-number-color: #EE7F18;
-    --code-parenthesis-color: #636363;
 }
diff --git a/_mydocs/analyze-in-excel/index.md b/_mydocs/analyze-in-excel/index.md
@@ -1,5 +1,5 @@
 ---
-layout:     home
+layout:     page
 title:      Analyze in Excel for Power BI Desktop
 menu_title: Analyze in Excel for Power BI 
 published:  false

diff --git a/_mydocs/api/index.md b/_mydocs/api/index.md
@@ -0,0 +1,12 @@
+---
+layout:         page
+title:          SQLBI API Reference (Beta)
+menu_title:     SQLBI API
+published:      true
+order:          /zzzz
+next_reading:   true
+next_reading_title: Available APIs
+---
+The SQLBI API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API is designed to be easy to use and to support the most common use cases. We have tried to make the API as predictable as possible, so you can easily predict the URLs and the structure of the JSON responses.
+
+> The SQLBI API are in **beta** and we are working to improve them. If you have any feedback, please [let us know](mailto:[email protected]?subject=SQLBI%20API).
diff --git a/_mydocs/api/licensing/courses.md b/_mydocs/api/licensing/courses.md
@@ -0,0 +1,79 @@
+---
+layout:     page
+title:      Courses
+published:  true
+order:      /1
+---
+The `Course` object contains information about the courses to which the license manager has access. This includes the total number of licenses, the number of licenses assigned, and the remaining licenses available for assignment. Additionally, it lists the license pools associated with each course, including the start and end dates of the pool, the number of licenses in the pool, and the number of licenses that have been assigned.
+
+## Endpoints
+
+`GET https://www.sqlbi.com/api/licensing/v1/courses`
+
+`GET https://www.sqlbi.com/api/licensing/v1/course/{id}`
+
+> Each endpoint is authenticated using a bearer token. The token must be included in the *Authorization* header of the request. See more in the [Authentication](index#authentication) section.
+
+### `GET` / v1 / courses
+Retrieve a list of all courses you have access to. Here is how to make this request using curl:
+
+```bash
+curl -X GET "https://www.sqlbi.com/api/licensing/v1/courses" \
+     -H "Authorization: Bearer eyJ0eXA*****"
+```
+
+#### Response
+A successful request will return a JSON array of courses. See the `Course` object response below for more details.
+
+#### Response Fields
+See the `Course` object fields below for a description of each field.
+
+### `GET` / v1 / course / {id}
+Retrieve detailed information about a specific course by providing the course ID:
+
+```bash
+curl -X GET "https://www.sqlbi.com/api/licensing/v1/course/37571" \
+     -H "Authorization: Bearer eyJ0eXA*****"
+```
+
+#### Response
+A JSON object containing detailed information about the specific course, including its license pools.
+
+```json
+// Course #37571
+{
+    "id": "37571",
+    "title": "Mastering DAX Video Course",
+    "licenses": 10,
+    "assignedLicenses": 4,
+    "availableLicenses": 6,
+    "pools": [
+        {
+            "id": 21,
+            "start": "2022-11-13T19:46:06+00:00",
+            "end": "2025-11-13T00:00:00+00:00",
+            "transferable": false,
+            "licenses": 1,
+            "assignedLicenses": 1,
+            "availableLicenses": 0
+        }
+    ]
+}
+```
+
+#### Response Fields
+Each `Course` object contains the following fields:
+
+- `id`: The unique identifier for the course.
+- `title`: The name of the course.
+- `licenses`: The total number of licenses purchased for the course.
+- `assignedLicenses`: The number of licenses that have already been assigned to students.
+- `availableLicenses`: The number of licenses that are currently unassigned and available for use.
+- `pools`: An array of license pools associated with the course. Each pool object includes:
+    - `id`: The unique identifier for the license pool.
+    - `start`: The start date and time for the license pool, formatted as an ISO 8601 date string.
+    - `end`: The expiration date and time of the license pool, also in ISO 8601 format.
+    - `transferable`: A boolean indicating whether the licenses in this pool are transferable (true) or untrasferable (false). [See the difference](https://www.sqlbi.com/transferable-video-course-licenses/). 
+    - `licenses`: The total number of licenses in the pool.
+    - `assignedLicenses`: The number of licenses from this pool that have been assigned.
+    - `availableLicenses`: The number of licenses from this pool that are currently available to be assigned.
diff --git a/_mydocs/api/licensing/index.md b/_mydocs/api/licensing/index.md
@@ -0,0 +1,75 @@
+---
+layout:     page
+title:      Licensing API
+menu_title: Licensing
+published:  true
+order:      /
+---
+This API allows SQLBI license managers to manage course licenses, including querying, assigning, and updating licenses across a variety of courses offered by SQLBI. It also enables the management of students and interrogation of their course progress.
+
+To become a license manager, you must have purchased an SQLBI video course with a transferable license (or with an *unassigned* untransferable license). If you are interested in learning more about our licensing options, please visit the [Transferable vs. Untransferable Licenses](https://www.sqlbi.com/transferable-video-course-licenses/) page.
+
+> Note the API is not required to manage your licenses since [we offer a web interface to manage them](https://www.sqlbi.com/license-manager-guide/). The API is intended for advanced users who want to automate the management of licenses or to integrate our licensing system with their own systems.
+
+## Base URL
+
+The base URL for the SQLBI Licensing API is:
+
+```
+https://www.sqlbi.com/api/licensing
+```
+
+## Authentication
+
+To access the Licensing API, you need to authenticate using a bearer token. This token must be included as a header in each of your requests. Here's how you can generate and use your API token:
+
+- Generate an API token in the [API section of the License Manager](https://www.sqlbi.com/license-manager-guide/#tokens).
+- Use this token by including it in the *Authorization* header as bearer token.  For example:
+
+```bash
+curl -X GET "https://www.sqlbi.com/api/licensing/v1/me" \
+     -H "Authorization: Bearer {token}"
+```
+
+> Note that the API token is a secret key that **should be kept confidential**. Do not share it in public forums or with unauthorized users. If you suspect that your token has been compromised, you can revoke the old one and regenerate it in the License Manager.
+
+## Errors
+
+The API uses standard HTTP status codes to indicate the success or failure of requests. Common responses include:
+
+- `200 OK`: The request was successful.
+- `400 Bad Request`: The request was invalid. Details about the error will be included in the response body.
+- `401 Unauthorized`: The request did not include a valid API token.
+- `403 Forbidden`: The provided API token does not have the necessary permissions for the requested operation.
+- `404 Not Found`: The requested resource does not exist.
+- `429 Too Many Requests`: You have hit the rate limit for the API.
+- `500 Internal Server Error`: An error occurred on the server. Please try again later.
+
+## Pagination
+
+To ensure the performance and reliability of the API, responses that return a list of items are paginated. The **default number of items per page is 10**. You can navigate through the pages using the `page` parameter and customize the page size using the `pageSize` parameter in your request.
+
+Example:  
+
+```bash
+curl -X GET "https://www.sqlbi.com/api/licensing/v1/students?page=2&pageSize=20" \
+     -H "Authorization: Bearer eyJ0eXA*****"
+```
+*Returns the second page of 20 students per page.*
+
+## Rate limits
+
+We implement rate limiting to ensure fair usage and stability of the API for all users. When you exceed the rate limit, you will receive a `429 Too Many Requests` response. 
+
+The current limit is set to **25 requests per minute**. 
+> Note that this limit may change over time based on usage patterns and server load.
+
+## Namespaces
+
+The Licensing API consists of several namespaces and endpoints that allow you to manage your licenses and students effectively:
+
+- [Me](me): Retrieve details about the license manager, including available licenses and pools.
+- [Courses](courses): Access the list of courses you have licenses for.
+- [Pools](pools): Manage your license pools.
+- [Licenses](licenses): Query and manage licenses assigned to students.
+- [Students](students): Get details about students and their course progress.
diff --git a/_mydocs/api/licensing/licenses.md b/_mydocs/api/licensing/licenses.md
@@ -0,0 +1,119 @@
+---
+layout:     page
+title:      Licenses
+published:  true
+order:      /3
+---
+The `License` object represents a course license assigned to a student. It includes the student's name, email address, the course title, the license start and end dates, and the license status.
+
+> While you can revoke a license by providing its id and using the `v1/license` endpoint, to assign a new license to a student, you must use to the `/v1/pool/` endpoint. See more in the [Pools](pools) section.
+
+## Endpoints
+
+`GET https://www.sqlbi.com/api/licensing/v1/licenses`
+
+`GET https://www.sqlbi.com/api/licensing/v1/license/{id}`
+
+`PATCH https://www.sqlbi.com/api/licensing/v1/license/{id}`
+
+`DELETE https://www.sqlbi.com/api/licensing/v1/license/{id}`
+
+> Each endpoint is authenticated using a bearer token. The token must be included in the *Authorization* header of the request. See more in the [Authentication](index#authentication) section.
+
+### `GET` / v1 / licenses  
+
+Retrieve a list of all assigned licenses with details about the associated student and course. Supports pagination and filtering inactive licenses.
+
+```bash
+curl -X GET "https://www.sqlbi.com/api/licensing/v1/licenses?pageSize=50" \
+     -H "Authorization: Bearer eyJ0eXA*****"
+```
+
+#### Query Parameters
+
+- `page`: (Optional) The page number to retrieve. Default is `1`.
+- `pageSize`: (Optional) The number of licenses to retrieve per page. Default is `10`.
+- `includeInactive`: (Optional) Whether to include inactive licenses in the response. Default is `false`.
+
+#### Response
+A JSON array of objects, each representing a license. See the `License` object response below for more details.
+
+#### Response Fields
+See the `License` object fields below for a description of each field.
+
+### `GET` / v1 / license / {id}
+
+Retrieve detailed information about a specific license by providing the license ID:
+
+```bash
+curl -X GET "https://www.sqlbi.com/api/licensing/v1/license/29" \
+     -H "Authorization: Bearer eyJ0eXA*****"
+```
+
+#### Response
+A JSON object detailing the specific license, including the student and course information.
+
+```json
+// License #29
+{
+    "id": "29",
+    "poolId": "26",
+    "courseId": "51030",
+    "start": "2024-04-17T15:23:08+00:00",
+    "end": "2025-01-01T00:00:00+00:00",
+    "active": true,
+    "revokable": true,
+    "editable": true,
+    "student": {
+        "id": "16521",
+        "name": "Student",
+        "email": "[email protected]"
+    }
+}
+```
+
+#### Response Fields
+
+- `id`: The unique identifier for the license.
+- `poolId`: The identifier of the pool from which the license is allocated.
+- `courseId`: The identifier of the course associated with the license.
+- `start`: The start date and time of the license validity period in ISO 8601 format.
+- `end`: The end date and time of the license validity period in ISO 8601 format.
+- `revokable`: A boolean indicating whether the license can be revoked (true) or not (false).
+- `editable`: A boolean indicating whether the license end date can be edited (true) or not (false).
+- `student`: An object containing:
+    - `id`: The unique identifier for the student.
+    - `name`: The name of the student.
+    - `email`: The email address of the student.
+
+
+### `PATCH` / v1 / license / {id}
+Update the expiration date of a license. Note that:
+- The update is allowed only if the parent license pool is transferable.
+- The uupdate is allowed only if the license is not expired. 
+- If you put a date in the past, the license will be immediately expired and cannot be updated anymore. 
+- If you put a date in the future, the license cannot be extended further than the pool expiration date.
+
+```bash
+curl -X PATCH "https://www.sqlbi.com/api/licensing/v1/license/29" \
+     -H "Authorization: Bearer eyJ0eXA*****" \
+     -H "Content-Type: application/json" \
+     -d '{"endDate": "2027-04-18"}'
+```
+
+#### Request Body
+- `endDate`: The new expiration date of the license in YYYY-MM-DD format.
+
+#### Response
+A JSON object representing the updated license.
+
+### `DELETE` / v1 / license / {id}
+Revoke a license. The license will be immediately expired, and the student will lose access to the course.
+
+```bash
+curl -X DELETE "https://www.sqlbi.com/api/licensing/v1/license/26" \
+     -H "Authorization: Bearer eyJ0eXA*****"
+```
+
+#### Response
+HTTP status code `200` if the operation is successful.
diff --git a/_mydocs/api/licensing/me.md b/_mydocs/api/licensing/me.md
@@ -0,0 +1,52 @@
+---
+layout:     page
+title:      Me
+published:  true
+order:      /0
+---
+The `Me` object contains information about the license manager, including the number of available license pools, the total number of licenses, and the breakdown of transferable vs. untransferable licenses. Additionally, it lists the domains that are authorized for assigning transferable licenses.
+
+## Endpoints
+
+`GET https://www.sqlbi.com/api/licensing/v1/me`
+
+> The endpoint is authenticated using a bearer token. The token must be included in the *Authorization* header of the request. See more in the [Authentication](index#authentication) section.
+
+### `GET` / v1 / me
+Retrieve the license manager's details. Here is how to make this request using curl:
+
+```bash
+curl -X GET "https://www.sqlbi.com/api/licensing/v1/me" \
+     -H "Authorization: Bearer eyJ0eXA*****"
+```
+
+#### Response
+Upon a successful request, the API will return a JSON object containing the details about the license manager. Below is an example of a JSON response:
+
+```json
+// License Manager #99999
+{
+    "id": 99999,
+    "name": "SQLBI",
+    "email": "[email protected]",
+    "pools": 13,
+    "licenses": 28,
+    "untrasferableLicenses": 24,
+    "transferableLicenses": 4,
+    "allowedDomainsForTransferableLicenses": [
+        "sqlbi.com"
+    ]
+}
+```
+
+#### Response Fields
+
+- `id`: The unique identifier of the license manager.
+- `name`: The name of the organization or individual managing the licenses.
+- `email`: The email address of the license manager.
+- `pools`: Number of license pools owned by the license manager.
+- `licenses`: The total number of licenses purchased.
+- `untransferableLicenses`: The number of untransferable licenses.
+- `transferableLicenses`: The number of transferable licenses.
+- `allowedDomainsForTransferableLicenses`: A list of domains allowed for assigning transferable licenses. 
+> While untransferable licenses can be assigned to any email address, transferable licenses can only be assigned to email addresses with domains listed here.