mirror/Part-DB.Part-DB-server
1
0
Fork 1
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2025-06-20 17:15:51 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added documentation about pagination and property filter to API docs.

Browse source
This commit is contained in:
Jan Böhmer 2023-09-18 13:02:45 +02:00
parent 6387c24c89
commit 915444b5da
2 changed files with 25 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

5
config/packages/api_platform.yaml
View file

@ -10,4 +10,7 @@ api_platform:
# overridden in OpenApiFactoryDecorator
access_token:
name: Authorization
type: header
type: header
defaults:
pagination_client_items_per_page: true # Allow clients to override the default items per page

22
docs/api/intro.md
View file

@ -13,6 +13,7 @@ This allows external applications to interact with Part-DB, extend it or integra
{: .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.
@ -68,4 +69,23 @@ API generators which can generate a client library for the API from the schema a
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.
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`).
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`).
See [API Platform docs](https://api-platform.com/docs/core/pagination) for more infos.
## 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.
See [API Platform docs](https://api-platform.com/docs/core/filters/#property-filter) for more infos.