From 0cf745b71fb118dfde4d2f760f3c25c99310f344 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 1 Nov 2024 12:32:19 +0200 Subject: [PATCH] updated docs Signed-off-by: bidi --- LICENSE | 2 +- composer.json | 4 ++-- docs/book/v4/commands/create-admin-account.md | 2 +- .../v4/commands/display-available-endpoints.md | 2 +- docs/book/v4/commands/generate-tokens.md | 2 +- docs/book/v4/core-features/authentication.md | 16 ++++++++-------- docs/book/v4/core-features/authorization.md | 8 ++++---- docs/book/v4/core-features/content-validation.md | 8 ++++---- docs/book/v4/core-features/cors.md | 2 +- docs/book/v4/core-features/exceptions.md | 4 ++-- docs/book/v4/flow/default-library-flow.md | 2 +- docs/book/v4/flow/library-flow-for-email.md | 2 +- docs/book/v4/flow/middleware-flow.md | 2 +- .../v4/installation/test-the-installation.md | 2 +- docs/book/v4/introduction/file-structure.md | 4 ++-- docs/book/v4/introduction/introduction.md | 10 +++++----- .../api-tools-vs-dotkernel-api.md | 4 ++-- docs/book/v4/tutorials/create-book-module.md | 2 +- docs/book/v4/tutorials/token-authentication.md | 4 ++-- docs/book/v5/commands/create-admin-account.md | 2 +- .../v5/commands/display-available-endpoints.md | 2 +- docs/book/v5/commands/generate-tokens.md | 2 +- docs/book/v5/core-features/authentication.md | 16 ++++++++-------- docs/book/v5/core-features/authorization.md | 8 ++++---- docs/book/v5/core-features/content-validation.md | 8 ++++---- docs/book/v5/core-features/cors.md | 2 +- .../v5/core-features/dependency-injection.md | 6 +++--- docs/book/v5/core-features/exceptions.md | 4 ++-- docs/book/v5/flow/default-library-flow.md | 2 +- docs/book/v5/flow/library-flow-for-email.md | 2 +- docs/book/v5/flow/middleware-flow.md | 2 +- docs/book/v5/installation/composer.md | 6 +++--- .../v5/installation/test-the-installation.md | 2 +- docs/book/v5/introduction/file-structure.md | 4 ++-- docs/book/v5/introduction/introduction.md | 10 +++++----- .../api-tools-vs-dotkernel-api.md | 4 ++-- docs/book/v5/tutorials/api-evolution.md | 2 +- docs/book/v5/tutorials/token-authentication.md | 4 ++-- mkdocs.yml | 6 +++--- 39 files changed, 88 insertions(+), 88 deletions(-) diff --git a/LICENSE b/LICENSE index 8fbc26c..7d6e18d 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2024 DotKernel +Copyright (c) 2024 Dotkernel Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/composer.json b/composer.json index fcc8fbc..feeb67f 100644 --- a/composer.json +++ b/composer.json @@ -1,11 +1,11 @@ { "name": "dotkernel/api-documentation", - "description": "DotKernel API documentation markdown files.", + "description": "Dotkernel API documentation markdown files.", "type": "metapackage", "license": "MIT", "authors": [ { - "name": "DotKernel Team", + "name": "Dotkernel Team", "email": "team@dotkernel.com" } ], diff --git a/docs/book/v4/commands/create-admin-account.md b/docs/book/v4/commands/create-admin-account.md index 28c84b6..6e43b49 100644 --- a/docs/book/v4/commands/create-admin-account.md +++ b/docs/book/v4/commands/create-admin-account.md @@ -1,4 +1,4 @@ -# Creating admin accounts in DotKernel API +# Creating admin accounts in Dotkernel API ## Usage diff --git a/docs/book/v4/commands/display-available-endpoints.md b/docs/book/v4/commands/display-available-endpoints.md index de197bc..7e257c1 100644 --- a/docs/book/v4/commands/display-available-endpoints.md +++ b/docs/book/v4/commands/display-available-endpoints.md @@ -1,4 +1,4 @@ -# Displaying DotKernel API endpoints using dot-cli +# Displaying Dotkernel API endpoints using dot-cli ## Usage diff --git a/docs/book/v4/commands/generate-tokens.md b/docs/book/v4/commands/generate-tokens.md index 340511d..bb795b4 100644 --- a/docs/book/v4/commands/generate-tokens.md +++ b/docs/book/v4/commands/generate-tokens.md @@ -1,4 +1,4 @@ -# Generating tokens in DotKernel API +# Generating tokens in Dotkernel API This is a multipurpose command that allows creating tokens required by different parts of the API. diff --git a/docs/book/v4/core-features/authentication.md b/docs/book/v4/core-features/authentication.md index b58769a..47d8541 100644 --- a/docs/book/v4/core-features/authentication.md +++ b/docs/book/v4/core-features/authentication.md @@ -3,14 +3,14 @@ Authentication is the process by which an identity is presented to the application. It ensures that the entity making the request has the proper credentials to access the API. -**DotKernel API** identities are delivered to the application from the client through the `Authorization` request. +**Dotkernel API** identities are delivered to the application from the client through the `Authorization` request. If it is present, the application tries to find and assign the identity to the application. If it is not presented, -DotKernel API assigns a default `guest` identity, represented by an instance of the class +Dotkernel API assigns a default `guest` identity, represented by an instance of the class `Mezzio\Authentication\UserInterface`. ## Configuration -Authentication in DotKernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already +Authentication in Dotkernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already configured out of the box. But if you want to dig more, the configuration is stored in `config/autoload/local.php` under the `authentication` key. @@ -20,17 +20,17 @@ configured out of the box. But if you want to dig more, the configuration is sto ## How it works -DotKernels API authentication system can be used for SPAs (single-page applications), mobile applications, and +Dotkernels API authentication system can be used for SPAs (single-page applications), mobile applications, and simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts. The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`. ## Database -When you install **DotKernel API** for the first time, you need to run the migrations and seeders. All the tables +When you install **Dotkernel API** for the first time, you need to run the migrations and seeders. All the tables required for authentication are automatically created and populated. -In DotKernel API, authenticated users come from either the `admin` or the `user` table. We choose to keep the admin +In Dotkernel API, authenticated users come from either the `admin` or the `user` table. We choose to keep the admin table separated from the users to prevent users of the application from accessing sensitive data, which only the administrators of the application should access. @@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api` ### Issuing API Tokens -Token generation in DotKernel API is done using the `password` `grand_type` scenario, which in this case allows +Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows authentication to an API using the user's credentials (generally a username and password). The client sends a POST request to the `/security/generate-token` with the following parameters: @@ -91,7 +91,7 @@ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9... ### Refreshing tokens -DotKernel API can refresh the access token, based on the expired access token's `refresh_token`. +Dotkernel API can refresh the access token, based on the expired access token's `refresh_token`. The clients need to send a `POST` request to the `/security/refresh-token` with the following request diff --git a/docs/book/v4/core-features/authorization.md b/docs/book/v4/core-features/authorization.md index cb98254..7891a24 100644 --- a/docs/book/v4/core-features/authorization.md +++ b/docs/book/v4/core-features/authorization.md @@ -3,12 +3,12 @@ Authorization is the process by which a system takes a validated identity and checks if that identity has access to a given resource. -**DotKernel API**'s implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of +**Dotkernel API**'s implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of Role-Based Access Control (RBAC). ## How it works -In DotKernel API each authenticatable entity (admin/user) comes with their roles table where you can define +In Dotkernel API each authenticatable entity (admin/user) comes with their roles table where you can define roles for each entity. RBAC comes in to ensure that each entity has the appropriate role and permission to access a resource. @@ -16,7 +16,7 @@ The authorization happens through the `Api\App\Middleware\AuthorizationMiddlewar ## Configuration -DotKernel API makes use of `mezzio-authorization-rbac` and includes the full configuration. +Dotkernel API makes use of `mezzio-authorization-rbac` and includes the full configuration. The configuration file for the role and permission definitions is `config/autoload/authorization.global.php`. @@ -68,7 +68,7 @@ Roles inherit the permissions from their parents: - `user` has no parent - `guest` has `user` as a parent which means `user` also has `guest` permissions -For each role we defined an array of permissions. A permission in DotKernel API is basically a route name. +For each role we defined an array of permissions. A permission in Dotkernel API is basically a route name. As you can see, the `superuser` does not have its own permissions, because it gains all the permissions from `admin`, no need to define explicit permissions. diff --git a/docs/book/v4/core-features/content-validation.md b/docs/book/v4/core-features/content-validation.md index 316e842..ec01f34 100644 --- a/docs/book/v4/core-features/content-validation.md +++ b/docs/book/v4/core-features/content-validation.md @@ -9,7 +9,7 @@ Essentially, content negotiation is the *client* telling the server what it is sending and what it wants in return, and the server determining if it can do what the client requests. -Content negotiation validation in **DotKernel API** happens through middleware, and it ensures that the incoming +Content negotiation validation in **Dotkernel API** happens through middleware, and it ensures that the incoming request and the outgoing response conform to the content types specified in the config file for all routes or for a specific route. @@ -18,7 +18,7 @@ errors responses when necessary. ## Configuration -In DotKernel API the configuration file for content negotiation is held +In Dotkernel API the configuration file for content negotiation is held in `config/autoload/content-negotiation.global.php` and the array looks like this: @@ -43,7 +43,7 @@ return [ ]; ``` -Except the `default` key, all your keys must match the route name, for example in DotKernel API we have the route to +Except the `default` key, all your keys must match the route name, for example in Dotkernel API we have the route to list all admins, which name is `admin.list`. If you did not specify a route name to configure your specifications about content negotiation, the `default` one will @@ -105,7 +105,7 @@ that route to be `multipart/form-data`. The above request will fail as the clien In addition to the validation described above, a third one is happening and is the last one: the server will check if the request `Accept` header can really be returned by the response. -Through the way **DotKernel API** is returning a response in handler, a content type is always set. +Through the way **Dotkernel API** is returning a response in handler, a content type is always set. This cannot be the case in any custom response but in any case the server will check what `Content-Type` the response is returning and will try to validate that against the `Accept` header of the request. diff --git a/docs/book/v4/core-features/cors.md b/docs/book/v4/core-features/cors.md index 7becc51..dd5264d 100644 --- a/docs/book/v4/core-features/cors.md +++ b/docs/book/v4/core-features/cors.md @@ -16,7 +16,7 @@ This happens because the API (_RESOURCE_URL_) is not configured to accept reques ## How to fix? -DotKernel API fixes this issue using the [mezzio/mezzio-cors](https://github.com/mezzio/mezzio-cors) library. +Dotkernel API fixes this issue using the [mezzio/mezzio-cors](https://github.com/mezzio/mezzio-cors) library. ### Step 1: Install library diff --git a/docs/book/v4/core-features/exceptions.md b/docs/book/v4/core-features/exceptions.md index 649e65f..764287f 100644 --- a/docs/book/v4/core-features/exceptions.md +++ b/docs/book/v4/core-features/exceptions.md @@ -9,7 +9,7 @@ code. ## How we use exceptions? -When it comes to handling exceptions, **DotKernel API** relies on the usage of easy-to-understand, problem-specific +When it comes to handling exceptions, **Dotkernel API** relies on the usage of easy-to-understand, problem-specific exceptions. Out-of-the-box we provide the following custom exceptions: @@ -53,7 +53,7 @@ Out-of-the-box we provide the following custom exceptions: ## How it works? -During a request, if there is no uncaught exception **DotKernel API** will return a JSON response with the data provided +During a request, if there is no uncaught exception **Dotkernel API** will return a JSON response with the data provided by the handler that handled the request. Else, it will build and send a response based on the exception thrown: diff --git a/docs/book/v4/flow/default-library-flow.md b/docs/book/v4/flow/default-library-flow.md index bbc6cef..894e2fa 100644 --- a/docs/book/v4/flow/default-library-flow.md +++ b/docs/book/v4/flow/default-library-flow.md @@ -1,5 +1,5 @@ # Default Library Flow -The graph below demonstrates a default flow between DotKernel's libraries. +The graph below demonstrates a default flow between Dotkernel's libraries. ![Dotkernel API Default Library Flow!](https://docs.dotkernel.org/img/api/dotkernel-library-flow.png) diff --git a/docs/book/v4/flow/library-flow-for-email.md b/docs/book/v4/flow/library-flow-for-email.md index 090035c..6c12457 100644 --- a/docs/book/v4/flow/library-flow-for-email.md +++ b/docs/book/v4/flow/library-flow-for-email.md @@ -1,5 +1,5 @@ # Library Flow for Email -The graph below demonstrates the simplified flow between DotKernel's libraries for sending an email. +The graph below demonstrates the simplified flow between Dotkernel's libraries for sending an email. ![Dotkernel API Default Library Flow!](https://docs.dotkernel.org/img/api/dotkernel-library-flow-email.png) diff --git a/docs/book/v4/flow/middleware-flow.md b/docs/book/v4/flow/middleware-flow.md index 95f73b4..5539489 100644 --- a/docs/book/v4/flow/middleware-flow.md +++ b/docs/book/v4/flow/middleware-flow.md @@ -1,5 +1,5 @@ # Middleware flow -The graph below demonstrates a default flow between DotKernel's middlewares. +The graph below demonstrates a default flow between Dotkernel's middlewares. ![Dotkernel API Middleware Flow!](https://docs.dotkernel.org/img/api/dotkernel-middleware-flow.png) diff --git a/docs/book/v4/installation/test-the-installation.md b/docs/book/v4/installation/test-the-installation.md index 47f49eb..9061b5d 100644 --- a/docs/book/v4/installation/test-the-installation.md +++ b/docs/book/v4/installation/test-the-installation.md @@ -2,7 +2,7 @@ Sending a GET request to the [home page](http://0.0.0.0:8080/) should output the following message: -> {"message": "DotKernel API version 4"} +> {"message": "Dotkernel API version 4"} ## Old way of doing things, using PHP built-in server diff --git a/docs/book/v4/introduction/file-structure.md b/docs/book/v4/introduction/file-structure.md index 43e4d72..566347a 100644 --- a/docs/book/v4/introduction/file-structure.md +++ b/docs/book/v4/introduction/file-structure.md @@ -4,7 +4,7 @@ Dotkernel API follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standards. It is a good practice to standardize the file structure of projects. -When using DotKernel API the following structure is installed by default: +When using Dotkernel API the following structure is installed by default: ![Dotkernel API File Structure!](https://docs.dotkernel.org/img/api/file-structure-dk-api.png) @@ -47,7 +47,7 @@ The `src` directory should also contain 2 files: This directory contains the template files, used for example to help render e-mail templates. -> DotKernel API uses twig as Templating Engine. All template files have the extension .html.twig +> Dotkernel API uses twig as Templating Engine. All template files have the extension .html.twig ## `data` directory diff --git a/docs/book/v4/introduction/introduction.md b/docs/book/v4/introduction/introduction.md index b91a68e..1d096f4 100644 --- a/docs/book/v4/introduction/introduction.md +++ b/docs/book/v4/introduction/introduction.md @@ -1,6 +1,6 @@ # Introduction -Based on Enrico Zimuel’s Zend Expressive API – Skeleton example, DotKernel API runs on Laminas and Mezzio components and implements standards like PSR-3, PSR-4, PSR-7, PSR-11 and PSR-15. +Based on Enrico Zimuel’s Zend Expressive API – Skeleton example, Dotkernel API runs on Laminas and Mezzio components and implements standards like PSR-3, PSR-4, PSR-7, PSR-11 and PSR-15. Here is a list of the core components: @@ -34,8 +34,8 @@ The benefit of Doctrine for the programmer is the ability to focus on the object Our documentation is Postman based. We use the following files in which we store information about every available endpoint ready to be tested: -* documentation/DotKernel_API.postman_collection.json -* documentation/DotKernel_API.postman_environment.json +* documentation/Dotkernel_API.postman_collection.json +* documentation/Dotkernel_API.postman_environment.json ## Hypertext Application Language @@ -47,11 +47,11 @@ By using `MezzioCorsMiddlewareCorsMiddleware`, the CORS preflight will be recogn ## OAuth 2.0 -OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on your DotKernel API. We are using mezzio/mezzio-authentication-oauth2 which provides OAuth 2.0 authentication for Mezzio and PSR-7/PSR-15 applications by using league/oauth2-server package. +OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on your Dotkernel API. We are using mezzio/mezzio-authentication-oauth2 which provides OAuth 2.0 authentication for Mezzio and PSR-7/PSR-15 applications by using league/oauth2-server package. ## Email -It is not unlikely for an API to send emails depending on the use case. Here is another area where DotKernel API shines. Using `DotMailServiceMailService` provided by dotkernel/dot-mail you can easily send custom email templates. +It is not unlikely for an API to send emails depending on the use case. Here is another area where Dotkernel API shines. Using `DotMailServiceMailService` provided by dotkernel/dot-mail you can easily send custom email templates. ## Configuration diff --git a/docs/book/v4/transition-from-api-tools/api-tools-vs-dotkernel-api.md b/docs/book/v4/transition-from-api-tools/api-tools-vs-dotkernel-api.md index 8ef9023..baf4064 100644 --- a/docs/book/v4/transition-from-api-tools/api-tools-vs-dotkernel-api.md +++ b/docs/book/v4/transition-from-api-tools/api-tools-vs-dotkernel-api.md @@ -1,6 +1,6 @@ -# Laminas API Tools compared to DotKernel API +# Laminas API Tools compared to Dotkernel API -| | API Tools (formerly Apigility) | DotKernel API | +| | API Tools (formerly Apigility) | Dotkernel API | |---------------------|------------------------------------------------|---------------------------------------------------------------------------------------| | URL | [api-tools](https://api-tools.getlaminas.org/) | [Dotkernel API](https://www.dotkernel.org) | | First Release | 2012 | 2018 | diff --git a/docs/book/v4/tutorials/create-book-module.md b/docs/book/v4/tutorials/create-book-module.md index 4dbc9d3..a667d62 100644 --- a/docs/book/v4/tutorials/create-book-module.md +++ b/docs/book/v4/tutorials/create-book-module.md @@ -1,4 +1,4 @@ -# Implementing a book module in DotKernel API +# Implementing a book module in Dotkernel API ## File structure diff --git a/docs/book/v4/tutorials/token-authentication.md b/docs/book/v4/tutorials/token-authentication.md index 8ff01ea..4fc40a2 100644 --- a/docs/book/v4/tutorials/token-authentication.md +++ b/docs/book/v4/tutorials/token-authentication.md @@ -11,7 +11,7 @@ and it consists of an alphanumeric string. In order to protect specific resources, clients need to be authenticated with user/admin roles. These roles are identified from the access token sent via the `Authorization` header. -When DotKernel API receives a request, it tries to read the access token. +When Dotkernel API receives a request, it tries to read the access token. If it does not find an access token, client has `guest` role: @@ -23,7 +23,7 @@ Else, client's account is identified and client has `admin`/`user` role (the one - if the requested endpoint is accessible to the client, the requested resource is returned - else, a `403 Forbidden` response is returned -DotKernel API provides out-of-the-box both an `admin` and a `user` account. +Dotkernel API provides out-of-the-box both an `admin` and a `user` account. The admin account with **role** set to both `superuser` and `admin` with the following credentials: diff --git a/docs/book/v5/commands/create-admin-account.md b/docs/book/v5/commands/create-admin-account.md index 28c84b6..6e43b49 100644 --- a/docs/book/v5/commands/create-admin-account.md +++ b/docs/book/v5/commands/create-admin-account.md @@ -1,4 +1,4 @@ -# Creating admin accounts in DotKernel API +# Creating admin accounts in Dotkernel API ## Usage diff --git a/docs/book/v5/commands/display-available-endpoints.md b/docs/book/v5/commands/display-available-endpoints.md index de197bc..7e257c1 100644 --- a/docs/book/v5/commands/display-available-endpoints.md +++ b/docs/book/v5/commands/display-available-endpoints.md @@ -1,4 +1,4 @@ -# Displaying DotKernel API endpoints using dot-cli +# Displaying Dotkernel API endpoints using dot-cli ## Usage diff --git a/docs/book/v5/commands/generate-tokens.md b/docs/book/v5/commands/generate-tokens.md index 340511d..bb795b4 100644 --- a/docs/book/v5/commands/generate-tokens.md +++ b/docs/book/v5/commands/generate-tokens.md @@ -1,4 +1,4 @@ -# Generating tokens in DotKernel API +# Generating tokens in Dotkernel API This is a multipurpose command that allows creating tokens required by different parts of the API. diff --git a/docs/book/v5/core-features/authentication.md b/docs/book/v5/core-features/authentication.md index b58769a..47d8541 100644 --- a/docs/book/v5/core-features/authentication.md +++ b/docs/book/v5/core-features/authentication.md @@ -3,14 +3,14 @@ Authentication is the process by which an identity is presented to the application. It ensures that the entity making the request has the proper credentials to access the API. -**DotKernel API** identities are delivered to the application from the client through the `Authorization` request. +**Dotkernel API** identities are delivered to the application from the client through the `Authorization` request. If it is present, the application tries to find and assign the identity to the application. If it is not presented, -DotKernel API assigns a default `guest` identity, represented by an instance of the class +Dotkernel API assigns a default `guest` identity, represented by an instance of the class `Mezzio\Authentication\UserInterface`. ## Configuration -Authentication in DotKernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already +Authentication in Dotkernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already configured out of the box. But if you want to dig more, the configuration is stored in `config/autoload/local.php` under the `authentication` key. @@ -20,17 +20,17 @@ configured out of the box. But if you want to dig more, the configuration is sto ## How it works -DotKernels API authentication system can be used for SPAs (single-page applications), mobile applications, and +Dotkernels API authentication system can be used for SPAs (single-page applications), mobile applications, and simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts. The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`. ## Database -When you install **DotKernel API** for the first time, you need to run the migrations and seeders. All the tables +When you install **Dotkernel API** for the first time, you need to run the migrations and seeders. All the tables required for authentication are automatically created and populated. -In DotKernel API, authenticated users come from either the `admin` or the `user` table. We choose to keep the admin +In Dotkernel API, authenticated users come from either the `admin` or the `user` table. We choose to keep the admin table separated from the users to prevent users of the application from accessing sensitive data, which only the administrators of the application should access. @@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api` ### Issuing API Tokens -Token generation in DotKernel API is done using the `password` `grand_type` scenario, which in this case allows +Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows authentication to an API using the user's credentials (generally a username and password). The client sends a POST request to the `/security/generate-token` with the following parameters: @@ -91,7 +91,7 @@ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9... ### Refreshing tokens -DotKernel API can refresh the access token, based on the expired access token's `refresh_token`. +Dotkernel API can refresh the access token, based on the expired access token's `refresh_token`. The clients need to send a `POST` request to the `/security/refresh-token` with the following request diff --git a/docs/book/v5/core-features/authorization.md b/docs/book/v5/core-features/authorization.md index cb98254..7891a24 100644 --- a/docs/book/v5/core-features/authorization.md +++ b/docs/book/v5/core-features/authorization.md @@ -3,12 +3,12 @@ Authorization is the process by which a system takes a validated identity and checks if that identity has access to a given resource. -**DotKernel API**'s implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of +**Dotkernel API**'s implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of Role-Based Access Control (RBAC). ## How it works -In DotKernel API each authenticatable entity (admin/user) comes with their roles table where you can define +In Dotkernel API each authenticatable entity (admin/user) comes with their roles table where you can define roles for each entity. RBAC comes in to ensure that each entity has the appropriate role and permission to access a resource. @@ -16,7 +16,7 @@ The authorization happens through the `Api\App\Middleware\AuthorizationMiddlewar ## Configuration -DotKernel API makes use of `mezzio-authorization-rbac` and includes the full configuration. +Dotkernel API makes use of `mezzio-authorization-rbac` and includes the full configuration. The configuration file for the role and permission definitions is `config/autoload/authorization.global.php`. @@ -68,7 +68,7 @@ Roles inherit the permissions from their parents: - `user` has no parent - `guest` has `user` as a parent which means `user` also has `guest` permissions -For each role we defined an array of permissions. A permission in DotKernel API is basically a route name. +For each role we defined an array of permissions. A permission in Dotkernel API is basically a route name. As you can see, the `superuser` does not have its own permissions, because it gains all the permissions from `admin`, no need to define explicit permissions. diff --git a/docs/book/v5/core-features/content-validation.md b/docs/book/v5/core-features/content-validation.md index 316e842..ec01f34 100644 --- a/docs/book/v5/core-features/content-validation.md +++ b/docs/book/v5/core-features/content-validation.md @@ -9,7 +9,7 @@ Essentially, content negotiation is the *client* telling the server what it is sending and what it wants in return, and the server determining if it can do what the client requests. -Content negotiation validation in **DotKernel API** happens through middleware, and it ensures that the incoming +Content negotiation validation in **Dotkernel API** happens through middleware, and it ensures that the incoming request and the outgoing response conform to the content types specified in the config file for all routes or for a specific route. @@ -18,7 +18,7 @@ errors responses when necessary. ## Configuration -In DotKernel API the configuration file for content negotiation is held +In Dotkernel API the configuration file for content negotiation is held in `config/autoload/content-negotiation.global.php` and the array looks like this: @@ -43,7 +43,7 @@ return [ ]; ``` -Except the `default` key, all your keys must match the route name, for example in DotKernel API we have the route to +Except the `default` key, all your keys must match the route name, for example in Dotkernel API we have the route to list all admins, which name is `admin.list`. If you did not specify a route name to configure your specifications about content negotiation, the `default` one will @@ -105,7 +105,7 @@ that route to be `multipart/form-data`. The above request will fail as the clien In addition to the validation described above, a third one is happening and is the last one: the server will check if the request `Accept` header can really be returned by the response. -Through the way **DotKernel API** is returning a response in handler, a content type is always set. +Through the way **Dotkernel API** is returning a response in handler, a content type is always set. This cannot be the case in any custom response but in any case the server will check what `Content-Type` the response is returning and will try to validate that against the `Accept` header of the request. diff --git a/docs/book/v5/core-features/cors.md b/docs/book/v5/core-features/cors.md index 7becc51..dd5264d 100644 --- a/docs/book/v5/core-features/cors.md +++ b/docs/book/v5/core-features/cors.md @@ -16,7 +16,7 @@ This happens because the API (_RESOURCE_URL_) is not configured to accept reques ## How to fix? -DotKernel API fixes this issue using the [mezzio/mezzio-cors](https://github.com/mezzio/mezzio-cors) library. +Dotkernel API fixes this issue using the [mezzio/mezzio-cors](https://github.com/mezzio/mezzio-cors) library. ### Step 1: Install library diff --git a/docs/book/v5/core-features/dependency-injection.md b/docs/book/v5/core-features/dependency-injection.md index b599a88..0ef7a19 100644 --- a/docs/book/v5/core-features/dependency-injection.md +++ b/docs/book/v5/core-features/dependency-injection.md @@ -6,12 +6,12 @@ terms, it's the act of providing dependencies for an object during instantiation In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter injection and property injection. -DotKernel API, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package +Dotkernel API, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package focuses only on constructor injection. ## Usage -**DotKernel API** comes out of the box with the +**Dotkernel API** comes out of the box with the [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package, which provides all we need for injecting dependencies into any object you want. @@ -57,5 +57,5 @@ public function getDependencies(): array That's it. When your object is instantiated from the container, it will automatically have its dependencies resolved. -> Dependencies injection is available to any object within DotKernel API. For example, you can inject dependencies in a +> Dependencies injection is available to any object within Dotkernel API. For example, you can inject dependencies in a > service, a handler and so on, simply by registering it in the `ConfigProvider`. diff --git a/docs/book/v5/core-features/exceptions.md b/docs/book/v5/core-features/exceptions.md index 649e65f..764287f 100644 --- a/docs/book/v5/core-features/exceptions.md +++ b/docs/book/v5/core-features/exceptions.md @@ -9,7 +9,7 @@ code. ## How we use exceptions? -When it comes to handling exceptions, **DotKernel API** relies on the usage of easy-to-understand, problem-specific +When it comes to handling exceptions, **Dotkernel API** relies on the usage of easy-to-understand, problem-specific exceptions. Out-of-the-box we provide the following custom exceptions: @@ -53,7 +53,7 @@ Out-of-the-box we provide the following custom exceptions: ## How it works? -During a request, if there is no uncaught exception **DotKernel API** will return a JSON response with the data provided +During a request, if there is no uncaught exception **Dotkernel API** will return a JSON response with the data provided by the handler that handled the request. Else, it will build and send a response based on the exception thrown: diff --git a/docs/book/v5/flow/default-library-flow.md b/docs/book/v5/flow/default-library-flow.md index bbc6cef..894e2fa 100644 --- a/docs/book/v5/flow/default-library-flow.md +++ b/docs/book/v5/flow/default-library-flow.md @@ -1,5 +1,5 @@ # Default Library Flow -The graph below demonstrates a default flow between DotKernel's libraries. +The graph below demonstrates a default flow between Dotkernel's libraries. ![Dotkernel API Default Library Flow!](https://docs.dotkernel.org/img/api/dotkernel-library-flow.png) diff --git a/docs/book/v5/flow/library-flow-for-email.md b/docs/book/v5/flow/library-flow-for-email.md index 090035c..6c12457 100644 --- a/docs/book/v5/flow/library-flow-for-email.md +++ b/docs/book/v5/flow/library-flow-for-email.md @@ -1,5 +1,5 @@ # Library Flow for Email -The graph below demonstrates the simplified flow between DotKernel's libraries for sending an email. +The graph below demonstrates the simplified flow between Dotkernel's libraries for sending an email. ![Dotkernel API Default Library Flow!](https://docs.dotkernel.org/img/api/dotkernel-library-flow-email.png) diff --git a/docs/book/v5/flow/middleware-flow.md b/docs/book/v5/flow/middleware-flow.md index 95f73b4..5539489 100644 --- a/docs/book/v5/flow/middleware-flow.md +++ b/docs/book/v5/flow/middleware-flow.md @@ -1,5 +1,5 @@ # Middleware flow -The graph below demonstrates a default flow between DotKernel's middlewares. +The graph below demonstrates a default flow between Dotkernel's middlewares. ![Dotkernel API Middleware Flow!](https://docs.dotkernel.org/img/api/dotkernel-middleware-flow.png) diff --git a/docs/book/v5/installation/composer.md b/docs/book/v5/installation/composer.md index ce1d167..b5f83b7 100644 --- a/docs/book/v5/installation/composer.md +++ b/docs/book/v5/installation/composer.md @@ -1,6 +1,6 @@ # Composer Installation of Packages -Composer is required to install DotKernel `frontend`. You can install Composer from the [official site](https://getcomposer.org/). +Composer is required to install Dotkernel `api`. You can install Composer from the [official site](https://getcomposer.org/). > First make sure that you have navigated your command prompt to the folder where you copied the files in the previous step. @@ -40,10 +40,10 @@ Please select which config file you wish to inject 'Laminas\Diactoros\ConfigProv Make your selection (default is 1): ``` -Type `0` to select `[0] Do not inject` because DotKernel includes its own ConfigProvider which already contains the prompted configurations. +Type `0` to select `[0] Do not inject`. +> We choose `0` because Dotkernel includes its own ConfigProvider which already contains the prompted configurations. > If you choose `[1] config/config.php`, an extra `ConfigProvider` will be injected. -> This is not required for the default installation, so make sure to select `[0] Do not inject`. The next question is: diff --git a/docs/book/v5/installation/test-the-installation.md b/docs/book/v5/installation/test-the-installation.md index af8ca3c..31823fa 100644 --- a/docs/book/v5/installation/test-the-installation.md +++ b/docs/book/v5/installation/test-the-installation.md @@ -2,7 +2,7 @@ Sending a GET request to the [home page](http://0.0.0.0:8080/) should output the following message: -> {"message": "DotKernel API version 5"} +> {"message": "Dotkernel API version 5"} ## Old way of doing things, using PHP built-in server diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md index 43e4d72..566347a 100644 --- a/docs/book/v5/introduction/file-structure.md +++ b/docs/book/v5/introduction/file-structure.md @@ -4,7 +4,7 @@ Dotkernel API follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standards. It is a good practice to standardize the file structure of projects. -When using DotKernel API the following structure is installed by default: +When using Dotkernel API the following structure is installed by default: ![Dotkernel API File Structure!](https://docs.dotkernel.org/img/api/file-structure-dk-api.png) @@ -47,7 +47,7 @@ The `src` directory should also contain 2 files: This directory contains the template files, used for example to help render e-mail templates. -> DotKernel API uses twig as Templating Engine. All template files have the extension .html.twig +> Dotkernel API uses twig as Templating Engine. All template files have the extension .html.twig ## `data` directory diff --git a/docs/book/v5/introduction/introduction.md b/docs/book/v5/introduction/introduction.md index 7103303..20d4064 100644 --- a/docs/book/v5/introduction/introduction.md +++ b/docs/book/v5/introduction/introduction.md @@ -1,6 +1,6 @@ # Introduction -Based on Enrico Zimuel’s Zend Expressive API – Skeleton example, DotKernel API runs on Laminas and Mezzio components and +Based on Enrico Zimuel’s Zend Expressive API – Skeleton example, Dotkernel API runs on Laminas and Mezzio components and implements standards like PSR-3, PSR-4, PSR-7, PSR-11 and PSR-15. Here is a list of the core components: @@ -37,8 +37,8 @@ persistence only as a secondary priority. Our documentation is Postman based. We use the following files in which we store information about every available endpoint ready to be tested: -* documentation/DotKernel_API.postman_collection.json -* documentation/DotKernel_API.postman_environment.json +* documentation/Dotkernel_API.postman_collection.json +* documentation/Dotkernel_API.postman_environment.json ## Hypertext Application Language @@ -54,12 +54,12 @@ match with all possible request methods. Therefore, for every preflight request, ## OAuth 2.0 OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on your -DotKernel API. We are using mezzio/mezzio-authentication-oauth2 which provides OAuth 2.0 authentication for Mezzio and +Dotkernel API. We are using mezzio/mezzio-authentication-oauth2 which provides OAuth 2.0 authentication for Mezzio and PSR-7/PSR-15 applications by using league/oauth2-server package. ## Email -It is not unlikely for an API to send emails depending on the use case. Here is another area where DotKernel API shines. +It is not unlikely for an API to send emails depending on the use case. Here is another area where Dotkernel API shines. Using `DotMailServiceMailService` provided by dotkernel/dot-mail you can easily send custom email templates. ## Configuration diff --git a/docs/book/v5/transition-from-api-tools/api-tools-vs-dotkernel-api.md b/docs/book/v5/transition-from-api-tools/api-tools-vs-dotkernel-api.md index eff7402..74e448b 100644 --- a/docs/book/v5/transition-from-api-tools/api-tools-vs-dotkernel-api.md +++ b/docs/book/v5/transition-from-api-tools/api-tools-vs-dotkernel-api.md @@ -1,6 +1,6 @@ -# Laminas API Tools compared to DotKernel API +# Laminas API Tools compared to Dotkernel API -| | API Tools (formerly Apigility) | DotKernel API | +| | API Tools (formerly Apigility) | Dotkernel API | |---------------------|------------------------------------------------|---------------------------------------------------------------------------------------| | URL | [api-tools](https://api-tools.getlaminas.org/) | [Dotkernel API](https://www.dotkernel.org) | | First Release | 2012 | 2018 | diff --git a/docs/book/v5/tutorials/api-evolution.md b/docs/book/v5/tutorials/api-evolution.md index 4d031a6..02b425b 100644 --- a/docs/book/v5/tutorials/api-evolution.md +++ b/docs/book/v5/tutorials/api-evolution.md @@ -5,7 +5,7 @@ planning and removing outdated features. ## How it works -In DotKernel API we can mark an entire endpoint or a single method as deprecated using attributes on handlers. +In Dotkernel API we can mark an entire endpoint or a single method as deprecated using attributes on handlers. We use response headers to inform the consumers about the future changes by using 2 new headers: - `Link` - it's a link to the official documentation pointing out the changes that will take place. diff --git a/docs/book/v5/tutorials/token-authentication.md b/docs/book/v5/tutorials/token-authentication.md index 3831d20..4f1c597 100644 --- a/docs/book/v5/tutorials/token-authentication.md +++ b/docs/book/v5/tutorials/token-authentication.md @@ -11,7 +11,7 @@ and it consists of an alphanumeric string. In order to protect specific resources, clients need to be authenticated with user/admin roles. These roles are identified from the access token sent via the `Authorization` header. -When DotKernel API receives a request, it tries to read the access token. +When Dotkernel API receives a request, it tries to read the access token. If it does not find an access token, client has `guest` role: @@ -23,7 +23,7 @@ Else, client's account is identified and client has `admin`/`user` role (the one - if the requested endpoint is accessible to the client, the requested resource is returned - else, a `403 Forbidden` response is returned -DotKernel API provides out-of-the-box both an `admin` and a `user` account. +Dotkernel API provides out-of-the-box both an `admin` and a `user` account. ### Credentials diff --git a/mkdocs.yml b/mkdocs.yml index 7732daa..d952ee8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,7 +45,7 @@ nav: - "API Evolution": v5/tutorials/api-evolution.md - "Find user by identity": v5/tutorials/find-user-by-identity.md - Transition from API Tools: - - "Laminas API Tools vs DotKernel API": v5/transition-from-api-tools/api-tools-vs-dotkernel-api.md + - "Laminas API Tools vs Dotkernel API": v5/transition-from-api-tools/api-tools-vs-dotkernel-api.md - "Transition Approach": v5/transition-from-api-tools/transition-approach.md - "Discovery Phase": v5/transition-from-api-tools/discovery-phase.md - OpenAPI: @@ -88,11 +88,11 @@ nav: - "Creating a book module": v4/tutorials/create-book-module.md - "Token authentication": v4/tutorials/token-authentication.md - Transition from API Tools: - - "Laminas API Tools vs DotKernel API": v4/transition-from-api-tools/api-tools-vs-dotkernel-api.md + - "Laminas API Tools vs Dotkernel API": v4/transition-from-api-tools/api-tools-vs-dotkernel-api.md - "Transition Approach": v4/transition-from-api-tools/transition-approach.md - "Discovery Phase": v4/transition-from-api-tools/discovery-phase.md site_name: api -site_description: "DotKernel API" +site_description: "Dotkernel API" repo_url: "https://github.com/dotkernel/api" plugins: - search