Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

updated composer, reqs page #65

Merged
merged 2 commits into from
Nov 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -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
Expand Down
4 changes: 2 additions & 2 deletions composer.json
Original file line number Diff line number Diff line change
@@ -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": "[email protected]"
}
],
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v4/commands/create-admin-account.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Creating admin accounts in DotKernel API
# Creating admin accounts in Dotkernel API

## Usage

Expand Down
2 changes: 1 addition & 1 deletion docs/book/v4/commands/display-available-endpoints.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Displaying DotKernel API endpoints using dot-cli
# Displaying Dotkernel API endpoints using dot-cli

## Usage

Expand Down
2 changes: 1 addition & 1 deletion docs/book/v4/commands/generate-tokens.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
16 changes: 8 additions & 8 deletions docs/book/v4/core-features/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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:
Expand Down Expand Up @@ -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

Expand Down
8 changes: 4 additions & 4 deletions docs/book/v4/core-features/authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,20 @@
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.

The authorization happens through the `Api\App\Middleware\AuthorizationMiddleware` middleware.

## 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`.

Expand Down Expand Up @@ -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.
Expand Down
8 changes: 4 additions & 4 deletions docs/book/v4/core-features/content-validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v4/core-features/cors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions docs/book/v4/core-features/exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v4/flow/default-library-flow.md
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 1 addition & 1 deletion docs/book/v4/flow/library-flow-for-email.md
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 1 addition & 1 deletion docs/book/v4/flow/middleware-flow.md
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 1 addition & 1 deletion docs/book/v4/installation/test-the-installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions docs/book/v4/introduction/file-structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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

Expand Down
10 changes: 5 additions & 5 deletions docs/book/v4/introduction/introduction.md
Original file line number Diff line number Diff line change
@@ -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:

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down
Original file line number Diff line number Diff line change
@@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v4/tutorials/create-book-module.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Implementing a book module in DotKernel API
# Implementing a book module in Dotkernel API

## File structure

Expand Down
4 changes: 2 additions & 2 deletions docs/book/v4/tutorials/token-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion docs/book/v5/commands/create-admin-account.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Creating admin accounts in DotKernel API
# Creating admin accounts in Dotkernel API

## Usage

Expand Down
2 changes: 1 addition & 1 deletion docs/book/v5/commands/display-available-endpoints.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Displaying DotKernel API endpoints using dot-cli
# Displaying Dotkernel API endpoints using dot-cli

## Usage

Expand Down
2 changes: 1 addition & 1 deletion docs/book/v5/commands/generate-tokens.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
16 changes: 8 additions & 8 deletions docs/book/v5/core-features/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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:
Expand Down Expand Up @@ -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

Expand Down
Loading