mirror of
https://github.com/Part-DB/Part-DB-server.git
synced 2025-06-24 10:49:00 +02:00
Fixed formatting and typos in documentation
This commit is contained in:
Jan Böhmer
parent
47fc7db953
commit
f32c0f52b6
24 changed files with 1512 additions and 730 deletions
|
|
@ -7,24 +7,31 @@ nav_order: 2
|
|||
|
||||
# Authentication
|
||||
|
||||
To use API endpoints, the external application has to authenticate itself, so that Part-DB knows which user is accessing the data and which permissions
|
||||
the application should have during the access. Authentication is always bound to a specific user, so the external applications is acting on behalf of a
|
||||
specific user. This user limits the permissions of the application, so that it can only access data, which the user is allowed to access.
|
||||
To use API endpoints, the external application has to authenticate itself, so that Part-DB knows which user is accessing
|
||||
the data and which permissions
|
||||
the application should have during the access. Authentication is always bound to a specific user, so the external
|
||||
applications is acting on behalf of a
|
||||
specific user. This user limits the permissions of the application, so that it can only access data, which the user is
|
||||
allowed to access.
|
||||
|
||||
The only method currently available for authentication is to use API tokens:
|
||||
|
||||
## API tokens
|
||||
|
||||
An API token is a long alphanumeric string, which is bound to a specific user and can be used to authenticate as this user, when accessing the API.
|
||||
The API token is passed via the `Authentication` HTTP header during the API request, like the following: `Authentication: Bearer tcp_sdjfks....`.
|
||||
An API token is a long alphanumeric string, which is bound to a specific user and can be used to authenticate as this
|
||||
user, when accessing the API.
|
||||
The API token is passed via the `Authentication` HTTP header during the API request, like the
|
||||
following: `Authentication: Bearer tcp_sdjfks....`.
|
||||
|
||||
{: .important }
|
||||
> Everbody who knows the API token can access the API as the user, which is bound to the token. So you should treat the API token like a password
|
||||
> Everybody who knows the API token can access the API as the user, which is bound to the token. So you should treat the
|
||||
> API token like a password
|
||||
> and keep it secret. Only share it with trusted applications.
|
||||
|
||||
API tokens can be created and managed on the user settings page in the API token section. You can create as many API tokens as you want and also delete them again.
|
||||
When deleting a token, it is immediately invalidated and can not be used anymore, which means that the application can not access the API anymore with this token.
|
||||
|
||||
API tokens can be created and managed on the user settings page in the API token section. You can create as many API
|
||||
tokens as you want and also delete them again.
|
||||
When deleting a token, it is immediately invalidated and can not be used anymore, which means that the application can
|
||||
not access the API anymore with this token.
|
||||
|
||||
### Token permissions and scopes
|
||||
|
||||
|
|
@ -32,22 +39,30 @@ API tokens are ultimately limited by the permissions of the user, which belongs
|
|||
can only access data, which the user is allowed to access, no matter the token permissions.
|
||||
|
||||
But you can further limit the permissions of a token by choosing a specific scope for the token. The scope defines which
|
||||
subset of permissions the token has, which can be less than the permissions of the user. For example you can have a user
|
||||
with full read and write permissions, but create a token with only read permissions, which can only read data, but not
|
||||
subset of permissions the token has, which can be less than the permissions of the user. For example, you can have a
|
||||
user
|
||||
with full read and write permissions, but create a token with only read permissions, which can only read data, but not
|
||||
change anything in the database.
|
||||
|
||||
{: .warning }
|
||||
> In general you should always use the least possible permissions for a token, to limit the possible damage, which can be done with a stolen token or a bug in the application.
|
||||
> Only use the full or admin scope, if you really need it, as they could potentially be used to do a lot of damage to your Part-DB instance.
|
||||
> In general, you should always use the least possible permissions for a token, to limit the possible damage, which can
|
||||
> be done with a stolen token or a bug in the application.
|
||||
> Only use the full or admin scope, if you really need it, as they could potentially be used to do a lot of damage to
|
||||
> your Part-DB instance.
|
||||
|
||||
Following token scopes are available:
|
||||
|
||||
* **Read-Only**: The token can only read non-sensitive data (like parts, but no users or groups) from the API and can not change anything.
|
||||
* **Edit**: The token can read and write non-sensitive data via the API. This includes creating, updating and deleting data. This should be enough for most applications.
|
||||
* **Admin**: The token can read and write all data via the API, including sensitive data like users and groups. This should only be used for trusted applications, which need to access sensitive data, and perform administrative actions.
|
||||
* **Full**: The token can do anything the user can do, including changing the users password and create new tokens. This should only be used for highly trusted applications!!
|
||||
* **Read-Only**: The token can only read non-sensitive data (like parts, but no users or groups) from the API and can
|
||||
not change anything.
|
||||
* **Edit**: The token can read and write non-sensitive data via the API. This includes creating, updating and deleting
|
||||
data. This should be enough for most applications.
|
||||
* **Admin**: The token can read and write all data via the API, including sensitive data like users and groups. This
|
||||
should only be used for trusted applications, which need to access sensitive data, and perform administrative actions.
|
||||
* **Full**: The token can do anything the user can do, including changing the users password and create new tokens. This
|
||||
should only be used for highly trusted applications!!
|
||||
|
||||
Please note, that in early versions of the API, there might be no endpoints yet, to really perform the actions, which would be allowed by the token scope.
|
||||
Please note, that in early versions of the API, there might be no endpoints yet, to really perform the actions, which
|
||||
would be allowed by the token scope.
|
||||
|
||||
### Expiration date
|
||||
|
||||
|
|
@ -57,5 +72,7 @@ and can be deleted there, but the code can not be used to access Part-DB anymore
|
|||
|
||||
### Get token information
|
||||
|
||||
When authenticating with an API token, you can get information about the currently used token by accessing the `/api/tokens/current` endpoint.
|
||||
It gives you information about the token scope, expiration date and the user, which is bound to the token and the last time the token was used.
|
||||
When authenticating with an API token, you can get information about the currently used token by accessing
|
||||
the `/api/tokens/current` endpoint.
|
||||
It gives you information about the token scope, expiration date and the user, which is bound to the token and the last
|
||||
time the token was used.
|
||||
|
|
@ -7,94 +7,126 @@ nav_order: 1
|
|||
|
||||
# Introduction
|
||||
|
||||
Part-DB provides a [REST API](https://en.wikipedia.org/wiki/REST) to programmatically access the data stored in the database.
|
||||
Part-DB provides a [REST API](https://en.wikipedia.org/wiki/REST) to programmatically access the data stored in the
|
||||
database.
|
||||
This allows external applications to interact with Part-DB, extend it or integrate it into other applications.
|
||||
|
||||
{: .warning }
|
||||
> This feature is currently in beta. Please report any bugs you find.
|
||||
> The API should not be considered stable yet and could change in future versions, without prior notice.
|
||||
> Some features might be missing or not working yet.
|
||||
> Also be aware, that there might be security issues in the API, which could allow attackers to access or edit data via the API, which
|
||||
> they normally should be able to access. So currently you should only use the API with trusted users and trusted applications.
|
||||
> Also be aware, that there might be security issues in the API, which could allow attackers to access or edit data via
|
||||
> the API, which
|
||||
> they normally should be able to access. So currently you should only use the API with trusted users and trusted
|
||||
> applications.
|
||||
|
||||
Part-DB uses [API Platform](https://api-platform.com/) to provide the API, which allows for easy creation of REST APIs with Symfony and gives you a lot of features out of the box.
|
||||
See the [API Platform documentation](https://api-platform.com/docs/core/) for more details about the API Platform features and how to use them.
|
||||
Part-DB uses [API Platform](https://api-platform.com/) to provide the API, which allows for easy creation of REST APIs
|
||||
with Symfony and gives you a lot of features out of the box.
|
||||
See the [API Platform documentation](https://api-platform.com/docs/core/) for more details about the API Platform
|
||||
features and how to use them.
|
||||
|
||||
## Enable the API
|
||||
|
||||
The API is available under the `/api` path, but not reachable without proper permissions.
|
||||
You have to give the users, which should be able to access the API the proper permissions (Misceallaneous -> API).
|
||||
Please note that there are two relevant permissions, the first one allows users to access the `/api/` path at all and showing the documentation,
|
||||
You have to give the users, which should be able to access the API the proper permissions (Miscellaneous -> API).
|
||||
Please note that there are two relevant permissions, the first one allows users to access the `/api/` path at all and
|
||||
showing the documentation,
|
||||
and the second one allows them to create API tokens which is needed for authentication of external applications.
|
||||
|
||||
|
||||
## Authentication
|
||||
|
||||
To use API endpoints, the external application has to authenticate itself, so that Part-DB knows which user is accessing the data and
|
||||
which permisions the application should have. Basically this is done by creating a API token for a user and then passing it on every request
|
||||
To use API endpoints, the external application has to authenticate itself, so that Part-DB knows which user is accessing
|
||||
the data and
|
||||
which permissions the application should have. Basically this is done by creating an API token for a user and then
|
||||
passing it on every request
|
||||
with the `Authorization` header as bearer token, so you add a header `Authorization: Bearer <your token>`.
|
||||
|
||||
See [Authentication chapter]({% link api/authentication.md %}) for more details.
|
||||
|
||||
## API endpoints
|
||||
|
||||
The API is split into different endpoints, which are reachable under the `/api/` path of your Part-DB instance (so `https://your-part-db.local/api/`).
|
||||
There are various endpoints for each entity type (like `part`, `manufacturer`, etc.), which allow you to read and write data and some special endpoints like `search` or `statistics`.
|
||||
The API is split into different endpoints, which are reachable under the `/api/` path of your Part-DB instance (
|
||||
so `https://your-part-db.local/api/`).
|
||||
There are various endpoints for each entity type (like `part`, `manufacturer`, etc.), which allow you to read and write
|
||||
data and some special endpoints like `search` or `statistics`.
|
||||
|
||||
For example all API endpoints for managing categories are available under `/api/categories/`. Depending on the exact path and the HTTP method used, you can read, create, update or delete categories.
|
||||
For example all API endpoints for managing categories are available under `/api/categories/`. Depending on the exact
|
||||
path and the HTTP method used, you can read, create, update or delete categories.
|
||||
For most entities, there are endpoints like this:
|
||||
|
||||
* **GET**: `/api/categories/` - List all categories in the database (with pagination of the results)
|
||||
* **POST**: `/api/categories/` - Create a new category
|
||||
* **GET**: `/api/categories/{id}` - Get a specific category by its ID
|
||||
* **DELETE**: `/api/categories/{id}` - Delete a specific category by its ID
|
||||
* **UPDATE**: `/api/categories/{id}` - Update a specific category by its ID. Only the fields which are sent in the request are updated, all other fields are left unchanged.
|
||||
Be aware that you have to set the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) content type header (`Content-Type: application/merge-patch+json`) for this to work.
|
||||
* **UPDATE**: `/api/categories/{id}` - Update a specific category by its ID. Only the fields which are sent in the
|
||||
request are updated, all other fields are left unchanged.
|
||||
Be aware that you have to set the [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) content type
|
||||
header (`Content-Type: application/merge-patch+json`) for this to work.
|
||||
|
||||
A full (interactive) list of endpoints can be displayed when visiting the `/api/` path in your browser, when you are logged in with a user, which is allowed to access the API.
|
||||
A full (interactive) list of endpoints can be displayed when visiting the `/api/` path in your browser, when you are
|
||||
logged in with a user, which is allowed to access the API.
|
||||
There is also a link to this page, on the user settings page in the API token section.
|
||||
This documentation also list all available fields for each entity type and the allowed operations.
|
||||
|
||||
## Formats
|
||||
|
||||
The API supports different formats for the request and response data, which you can control via the `Accept` and `Content-Type` headers.
|
||||
You should use [JSON-LD](https://json-ld.org/) as format, which is basically JSON with some additional metadata, which allows
|
||||
to describe the data in a more structured way and also allows to link between different entities. You can achieve this by setting `Accept: application/ld+json` header to the API requests.
|
||||
The API supports different formats for the request and response data, which you can control via the `Accept`
|
||||
and `Content-Type` headers.
|
||||
You should use [JSON-LD](https://json-ld.org/) as format, which is basically JSON with some additional metadata, which
|
||||
allows
|
||||
to describe the data in a more structured way and also allows to link between different entities. You can achieve this
|
||||
by setting `Accept: application/ld+json` header to the API requests.
|
||||
|
||||
To get plain JSON without any metadata or links, use the `Accept: application/json` header.
|
||||
|
||||
Without an `Accept` header (e.g. when you call the endpoint in a browser), the API will return a HTML page with the documentation, so be sure to include the desired `Accept` header in your API requests.
|
||||
If you can not control the `Accept` header, you can add an `.json` or `.jsonld` suffix to the URL to enforce a JSON or JSON-LD response (e.g. `/api/parts.jsonld`).
|
||||
Without an `Accept` header (e.g. when you call the endpoint in a browser), the API will return an HTML page with the
|
||||
documentation, so be sure to include the desired `Accept` header in your API requests.
|
||||
If you can not control the `Accept` header, you can add an `.json` or `.jsonld` suffix to the URL to enforce a JSON or
|
||||
JSON-LD response (e.g. `/api/parts.jsonld`).
|
||||
|
||||
## OpenAPI schema
|
||||
|
||||
Part-DB provides a [OpenAPI](https://swagger.io/specification/) (formally Swagger) schema for the API under `/api/docs.json` (so `https://your-part-db.local/api/docs.json`).
|
||||
This schema is a machine readable description of the API, which can be imported in software to test the API or even automatically generate client libraries for the API.
|
||||
Part-DB provides a [OpenAPI](https://swagger.io/specification/) (formally Swagger) schema for the API
|
||||
under `/api/docs.json` (so `https://your-part-db.local/api/docs.json`).
|
||||
This schema is a machine-readable description of the API, which can be imported in software to test the API or even
|
||||
automatically generate client libraries for the API.
|
||||
|
||||
API generators which can generate a client library for the API from the schema are available for many programming languages, like [OpenAPI Generator](https://openapi-generator.tech/).
|
||||
API generators which can generate a client library for the API from the schema are available for many programming
|
||||
languages, like [OpenAPI Generator](https://openapi-generator.tech/).
|
||||
|
||||
An JSONLD/Hydra version of the schema is also available under `/api/docs.jsonld` (so `https://your-part-db.local/api/docs.jsonld`).
|
||||
An JSONLD/Hydra version of the schema is also available under `/api/docs.jsonld` (
|
||||
so `https://your-part-db.local/api/docs.jsonld`).
|
||||
|
||||
## Interactive documentation
|
||||
|
||||
Part-DB provides an interactive documentation for the API, which is available under `/api/docs` (so `https://your-part-db.local/api/docs`).
|
||||
You can pass your API token in the form on the top of the page, to authenticate yourself and then you can try out the API directly in the browser.
|
||||
Part-DB provides an interactive documentation for the API, which is available under `/api/docs` (
|
||||
so `https://your-part-db.local/api/docs`).
|
||||
You can pass your API token in the form on the top of the page, to authenticate yourself, and then you can try out the
|
||||
API directly in the browser.
|
||||
This is a great way to test the API and see how it works, without having to write any code.
|
||||
|
||||
## Pagination
|
||||
|
||||
By default all list endpoints are paginated, which means only a certain number of results is returned per request.
|
||||
To get another page of the results, you have to use the `page` query parameter, which contains the page number you want to get (e.g. `/api/categoues/?page=2`).
|
||||
By default, all list endpoints are paginated, which means only a certain number of results is returned per request.
|
||||
To get another page of the results, you have to use the `page` query parameter, which contains the page number you want
|
||||
to get (e.g. `/api/categoues/?page=2`).
|
||||
When using JSONLD, the links to the next page are also included in the `hydra:view` property of the response.
|
||||
|
||||
To change the size of the pages (the number of items in a single page) use the `itemsPerPage` query parameter (e.g. `/api/categoues/?itemsPerPage=50`).
|
||||
To change the size of the pages (the number of items in a single page) use the `itemsPerPage` query parameter (
|
||||
e.g. `/api/categoues/?itemsPerPage=50`).
|
||||
|
||||
See [API Platform docs](https://api-platform.com/docs/core/pagination) for more infos.
|
||||
|
||||
## Filtering results / Searching
|
||||
|
||||
When retrieving a list of entities, you can restrict the results by various filters. Almost all entities have a search filter,
|
||||
which allows you to only include entities, which (text) fields match the given search term: For example if you only want to
|
||||
get parts, with the Name "BC547", you can use `/api/parts.jsonld?name=BC547`. You can use `%` as wildcard for multiple characters
|
||||
in the search term (Be sure to properly encode the search term, if you use special characters). For example if you want to get all parts,
|
||||
When retrieving a list of entities, you can restrict the results by various filters. Almost all entities have a search
|
||||
filter,
|
||||
which allows you to only include entities, which (text) fields match the given search term: For example if you only want
|
||||
to
|
||||
get parts, with the Name "BC547", you can use `/api/parts.jsonld?name=BC547`. You can use `%` as wildcard for multiple
|
||||
characters
|
||||
in the search term (Be sure to properly encode the search term, if you use special characters). For example if you want
|
||||
to get all parts,
|
||||
whose name starts with "BC", you can use `/api/parts.jsonld?name=BC%25` (the `%25` is the url encoded version of `%`).
|
||||
|
||||
There are other filters available for some entities, allowing you to search on other fields, or restricting the results
|
||||
|
|
@ -102,35 +134,45 @@ by numeric values or dates. See the endpoint documentation for the available fil
|
|||
|
||||
## Filter by associated entities
|
||||
|
||||
To get all parts with a certain category, manufacturer, etc. you can use the `category`, `manufacturer`, etc. query parameters of the `/api/parts` endpoint.
|
||||
They are so called entitiy filters and accept a comma separated list of IDs of the entities you want to filter by.
|
||||
For example if you want to get all parts with the category "Resistor" (Category ID 1) and "Capacitor" (Category ID 2), you can use `/api/parts.jsonld?category=1,2`.
|
||||
To get all parts with a certain category, manufacturer, etc. you can use the `category`, `manufacturer`, etc. query
|
||||
parameters of the `/api/parts` endpoint.
|
||||
They are so-called entity filters and accept a comma separated list of IDs of the entities you want to filter by.
|
||||
For example if you want to get all parts with the category "Resistor" (Category ID 1) and "Capacitor" (Category ID 2),
|
||||
you can use `/api/parts.jsonld?category=1,2`.
|
||||
|
||||
Suffix an id with `+` to suffix, to include all direct children categories of the given category. Use the `++` suffix to include all children categories recursively.
|
||||
To get all parts with the category "Resistor" (Category ID 1) and all children categories of "Capacitor" (Category ID 2), you can use `/api/parts.jsonld?category=1,2++`.
|
||||
Suffix an id with `+` to suffix, to include all direct children categories of the given category. Use the `++` suffix to
|
||||
include all children categories recursively.
|
||||
To get all parts with the category "Resistor" (Category ID 1) and all children categories of "Capacitor" (Category ID
|
||||
2), you can use `/api/parts.jsonld?category=1,2++`.
|
||||
|
||||
See the endpoint documentation for the available entity filters.
|
||||
|
||||
## Ordering results
|
||||
|
||||
When retrieving a list of entities, you can order the results by various fields using the `order` query parameter.
|
||||
For example if you want to get all parts ordered by their name, you can use `/api/parts/?order[name]=asc`. You can use
|
||||
For example if you want to get all parts ordered by their name, you can use `/api/parts/?order[name]=asc`. You can use
|
||||
this parameter multiple times to order by multiple fields.
|
||||
|
||||
See the endpoint documentation for the available fields to order by.
|
||||
|
||||
## Property filter
|
||||
|
||||
Sometimes you only want to get a subset of the properties of an entity, for example when you only need the name of a part, but not all the other properties.
|
||||
You can achieve this using the `properties[]` query parameter with the name of the field you want to get. You can use this parameter multiple times to get multiple fields.
|
||||
For example if you only want to get the name and the description of a part, you can use `/api/parts/123?properties[]=name&properties[]=description`.
|
||||
It is also possible to use this filters on list endpoints (get collection), to only get a subset of the properties of all entities in the collection.
|
||||
Sometimes you only want to get a subset of the properties of an entity, for example when you only need the name of a
|
||||
part, but not all the other properties.
|
||||
You can achieve this using the `properties[]` query parameter with the name of the field you want to get. You can use
|
||||
this parameter multiple times to get multiple fields.
|
||||
For example if you only want to get the name and the description of a part, you can
|
||||
use `/api/parts/123?properties[]=name&properties[]=description`.
|
||||
It is also possible to use this filters on list endpoints (get collection), to only get a subset of the properties of
|
||||
all entities in the collection.
|
||||
|
||||
See [API Platform docs](https://api-platform.com/docs/core/filters/#property-filter) for more infos.
|
||||
|
||||
## Change comment
|
||||
|
||||
Similar to the changes using Part-DB web interface, you can add a change comment to every change you make via the API, which will be
|
||||
Similar to the changes using Part-DB web interface, you can add a change comment to every change you make via the API,
|
||||
which will be
|
||||
visible in the log of the entity.
|
||||
|
||||
You can pass the text for this via the `_comment` query parameter (beware the proper encoding). For example `/api/parts/123?_comment=This%20is%20a%20change%20comment`.
|
||||
You can pass the text for this via the `_comment` query parameter (beware the proper encoding). For
|
||||
example `/api/parts/123?_comment=This%20is%20a%20change%20comment`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue