inventree/inventree-docs
2
0
Fork 0
mirror of https://github.com/inventree/inventree-docs.git synced 2025-06-15 03:35:35 +00:00
Code Activity

API docs (#379)

Browse Source 
* Move API documentation into separate directory

* Rearrange main docs bar

* Split python examples into separate page

* Fix broken links

* Adds page for browseable API

* Fix image links

* Add entrypoint page for barcodes

* Update barcode docs

* Add (empty) pages for internal and external barcods

* Add documentation on "internal" barcode format

* Documentation for external barcode functionality

* Skeleton page for custom barcode information

* Extend docs for custom barcodesplugins

* Add stubs for new API docs

* Add documentation for downloading data via the AP

* API metadata information

* docs for pythonic metadata access

* docs for bulk delete
This commit is contained in:
Oliver
2022-10-29 14:46:06 +11:00
committed by GitHub
parent 415accae21
commit 48baf7e051
30 changed files with 572 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/api/api.md Normal file
View File

@ -0,0 +1,111 @@
---
title: InvenTree API
---
## InvenTree API
InvenTree provides a powerful REST API for interacting with inventory data on the server. Low-level data access and manipulation is available, with integrated user authentication and data validation.
!!! info "Django REST Framework"
The InvenTree API is based on the powerful and flexible [Django REST Framework](https://www.django-rest-framework.org/).
## Documentation
The API is self-documenting, and the documentation is provided alongside any InvenTree installation instance. If (for example) you have an InvenTree instance running at `http://127.0.0.1:8000` then the API documentation is available at `http://127.0.0.1:8000/api-doc/`
{% with id="api_doc", url="api/api_doc.png", description="API documentation" %}
{% include 'img.html' %}
{% endwith %}
## Authentication
Users must be authenticated to gain access to the InvenTree API. The API accepts either basic username:password authentication, or token authentication. Token authentication is recommended as it provides much faster API access.
!!! warning "Permissions"
API access is restricted based on the permissions assigned to the user.
### Basic Auth
Users can authenticate against the API using basic authentication - specifically a valid combination of `username` and `password` credentials.
### Tokens
Each user is assigned an authentication token which can be used to access the API. This token is persistent for that user (unless invalidated by an administrator) and can be used across multiple sessions.
!!! info "Token Administration"
User tokens can be created and/or invalidated via the Admin interface.
### Requesting a Token
If a user does not know their access token, it can be requested via the API interface itself, using a basic authentication request.
To obtain a valid token, perform a GET request to `/api/user/token/`. No data are required, but a valid username / password combination must be supplied in the authentication headers.
!!! info "Credentials"
Ensure that a valid username:password combination are supplied as basic authorization headers.
Once a valid token is received from the server, subsequent API requests should be performed using that token.
If the supplied user credentials are validated, the server will respond with:
```
HTTP_200_OK
{
token: "usertokendatastring",
}
```
### Using a Token
After reception of a valid authentication token, it can be subsequently used to perform token-based authentication.
The token value sent to the server must be of the format `Token <TOKEN-VALUE>` (without the `<` and `>` characters).
**Example: Javascript**
```javascript
var token = "MY-TOKEN-VALUE-HERE";
$.ajax({
url: "http://localhost:8080/api/part/",
type: 'GET',
headers: {"Authorization": `Token ${token}`}
});
```
**Example: Python (Requests)**
```python
import requests
token = 'MY-TOKEN-VALUE-HERE'
data = { ... }
headers = {
'AUTHORIZATION': f'Token {token}'
}
response = request.get('http://localhost:8080/api/part/', data=data, headers=headers)
```
## Authorization
### User Roles
Users can only perform REST API actions which align with their assigned [role permissions](../settings/permissions.md#roles).
Once a user has *authenticated* via the API, a list of the available roles can be retrieved from:
`/api/user/roles/`
For example, when accessing the API from a *superuser* account:
{% with id="api_roles", url="api/api_roles.png", description="API superuser roles" %}
{% include 'img.html' %}
{% endwith %}
Or, when accessing the API from an account which has read-only permissions:
{% with id="api_roles_2", url="api/api_roles_2.png", description="API user roles" %}
{% include 'img.html' %}
{% endwith %}
### Permission Denied
If an API action outside of the user's role(s) is attempted, the server will respond with a 403 permission error message.

37
docs/api/browse.md Normal file
View File

@ -0,0 +1,37 @@
---
title: Interactive API
---
## Interactive API
If the server is running in [Debug Mode](../start/intro.md#debug-mode) then an interactive version of the API is available using a browser.
!!! info "Debug Mode"
This interactive API is only available when running the server in debug mode
!!! warning "Slow Traffic Ahead"
The interactive API is *significantly* slower than using the normal JSON format. It is provided only for development and testing.
### List View
Various list endpoints can be displayed as shown below:
{% with id="api_browse", url="api/api_browse.png", description="List API" %}
{% include 'img.html' %}
{% endwith %}
### Filtering
List views can be filtered interactively:
{% with id="api_filter", url="api/api_filters.png", description="Filter API" %}
{% include 'img.html' %}
{% endwith %}
### Detail View
Detail view endpoints can also be displayed:
{% with id="api_detail", url="api/api_detail.png", description="Detail API" %}
{% include 'img.html' %}
{% endwith %}

44
docs/api/bulk_delete.md Normal file
View File

@ -0,0 +1,44 @@
---
title: Bulk Deletion
---
## Bulk Deletion
While deleting items individually via the API is supported, it can prove inefficient (time consuming) when multiple items are to be deleted sequentially.
For example, if the user wishes to delete a large number items (such as lines from a [Bill of Materials](../build/bom.md)), these items are deleted sequentially, with each `DELETE` separate request requiring network transfer, database access, cleanup, etc.
A much more efficient approach is to allow for "bulk deletion" of multiple database items in a single transaction. This means that only one network request is required, and only a single database access request.
So, InvenTree supports a custom "bulk deletion" endpoint which is available for some database models.
## Item Filtering
In a "regular" `DELETE` action, the pk (primary key) of the target object is provided, to designate which object is going to be removed from the database:
`DELETE /api/part/10/`
However this approach does not work if we wish to delete multiple items. To determine which items are to be deleted, additional data can be added to the query (as you would do with a normal `POST` request, for example).
### Primary Key Values
The request can specify a list of individual pk (primary key) values to delete, using the `items` variable:
```json
{
"items": [1, 10, 50, 99]
}
```
### Filters
The request can also specify a list of filters to be applied to the database query. Any items which match the filters will be deleted. Here, use the `filters` variable:
```
{
"filters": {
"active": False,
"category": 7.
}
}
```

23
docs/api/download.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Data Download
---
## Data Download
Some API endpoints provide a *download* function, whereby the data presented at the API endpoint can be downloaded as a tabulated file.
To export API data to a file, add the `&export=<format>` modifier to the query. The following file formats are supported:
| File Format | Modifier |
| --- | --- |
| csv | `&format=csv` |
| tsv | `&format=tsv` |
| xls | `&format=xls` |
| xlsx | `&format=xlsx` |
### Query Filters
Any other query filters used in the API request are also observed when downloading the data. For example, to download a list of all stock items in a given location:
`<host>/api/stock/?format=csv&location=10`

92
docs/api/metadata.md Normal file
View File

@ -0,0 +1,92 @@
---
title: Model Metadata
---
## Model Metadata
The API is *self describing* in that it provides metadata about the various fields available at any given endpoint. External applications (such as the [python interface](../api/python/python.md)) can introspect the API to determine information about the model fields.
!!! tip "API Forms"
The various forms implemented in the InvenTree web interface make heavy use of this metadata feature
### Requesting Metadata
To request metadata about a particular API endpoint, simply perform an `OPTIONS` method request against the API URL.
For example, to view the metadata available for creating a new [Part Category](../part/part.md#part-category), an `OPTIONS` request to `/api/part/category/` yields:
{% with id="api_cat_options", url="api/api_category_options.png", description="Part category options" %}
{% include 'img.html' %}
{% endwith %}
You can see here a detailed list of the various fields which are available for this API endpoint.
## Metadata Information
The `OPTIONS` endpoint provides the following information:
| Entry | Description |
| --- | --- |
| name | The human-readable name of the API endpoint |
| description | Descriptive detail for the endpoint, extracted from the python docstring |
| actions | Contains the available HTTP actions and field information (see below) |
Specific details are provided on the available attributes of each field:
{% with id="api_fields", url="api/api_metadata_fields.png", description="Metadata fields" %}
{% include 'img.html' %}
{% endwith %}
### Field Types
Supported field types are:
| Field Type | Description |
| --- | --- |
| string | Text data |
| boolean | true / false value |
| integer | Integer numbers |
| float | Floating point numbers |
| related field | Primary key value for a foreign-key relationship in the database |
### Field Attributes
Each named field provides information on available attributes:
| Attribute | Description |
| --- | --- |
| type | Defines the [field type](#field-types) |
| default | The default value for this field. Will be assumed if no value is supplied |
| required | Boolean value, whether this field must be supplied |
| read_only | Boolean value, whether this field is writeable |
| label | Human readable descriptive label for this field. |
| help_text | Long form descriptor for this field. |
| min_value | Minimum allowed value (for numeric fields) |
| max_value | Maximum allowed value (for numeric fields) |
| max_length | Maximum allowed length (for text fields) |
| model | Name of the database model, if this field represents a foreign-key relationship |
| api_url | API url for the related model, if this field represents a foreign-key relationship |
| filters | API filters for the field, if this field represents a foreign-key relationship |
!!! tip "Field Name"
The field name is the *key* used to define the field itself
!!! info "Available Attributes"
Some attributes may not be made available for a particular field
## Translation
Field *label* and *help text* values are localized using the [community contributed translations](../contribute.md#translation). The required locale information is determined from the API request itself, meaning that the translated values are provided automatically.
For example, the same forms (in the web interface) are served via identical API requests, with the locale information determined "on the fly":
{% with id="api_english", url="api/api_english.png", description="API forms (english)" %}
{% include 'img.html' %}
{% endwith %}
{% with id="api_german", url="api/api_german.png", description="API forms (german)" %}
{% include 'img.html' %}
{% endwith %}

224
docs/api/python/examples.md Normal file
View File

@ -0,0 +1,224 @@
---
title: Python Interface Examples
---
## Examples
Following is a *non-exhaustive* list of examples of the capabilities provided by the python library. For a complete look at what it can do, [read the source code](https://github.com/inventree/inventree-python)!
### Creating New Items
Use the `create` method to add new items to the database:
```python
from inventree.part import Part, PartCategory
from inventree.stock import StockItem
## Create a new PartCategory object,
## underneath the existing category with pk 7. Leave the parent empty fpr a top level category
furniture = PartCategory.create(api, {
'name': 'Furniture',
'description': 'Chairs, tables, etc',
'parent': 7,
})
## Create a new Part
## Use the pk (primary-key) of the newly created category
couch = Part.create(api, {
'name': 'Couch',
'description': 'Long thing for sitting on',
'category': furniture.pk,
'active': True,
'virtual': False,
## Note - You do not have to fill out *all* fields
})
```
### Updating Attributes
Most model fields which are exposed via the API can be directly edited using the python interface, by simply calling the `save()` method as shown below:
```python
from inventree.api import InvenTreeAPI
from inventree.part import Part
api = InvenTreeAPI(host='http://localhost:8000', username='admin', password='inventree')
# Retrieve part instance with primary-key of 1
part = Part(api, pk=1)
# Update specified part parameters
part.save(data={
"description": "New part description",
"minimum_stock": 250,
})
# Reload data from remote server
part.reload()
# Display updated data
print("Part Name:", part.name)
print("Description:", part.description)
print("Minimum stock:", part.minimum_stock)
```
!!! info "Read Only Fields"
Note that some fields are read-only and cannot be edited via the API
### Adding Parameters
Each [part](../../part/part.md) can have multiple [parameters](../../part/parameter.md). For the example of the sofa (above) *length* and *weight* make sense. Each parameter has a parameter template that combines the parameter name with a unit. So we first have to create the parameter templates and afterwards add the parameter values to the sofa.
```python
from inventree.part import Parameter
from inventree.part import ParameterTemplate
LengthTemplate = ParameterTemplate.create(api, { 'name' : 'Length', 'units' : 'Meters' })
WeightTemplate = ParameterTemplate.create(api, { 'name' : 'Weight', 'units' : 'kg' })
ParameterLength = Parameter.create(api, { 'part': couch.pk, 'template': LengthTemplate.pk, 'data' : 2 })
ParameterWeight = Parameter.create(api, { 'part': couch.pk, 'template': WeightTemplate.pk, 'data' : 60 })
```
These parameter templates need to be defined only once and can be used for all other parts. Lets finally add a picture.
```python
couch.upload_image('my_nice_couch.jpg')
```
### Adding Location Data
If we have several sofas on stock we need to know there we have stored them. So let’s add stock locations to the part. Stock locations can be organized in a hierarchical manner e.g. boxes in shelves in aisles in rooms. So each location can have a parent. Let’s assume we have 10 sofas in box 12 and 3 sofas in box 13 located in shelve 43 aisle 3. First we have to create the locations, afterwards we can put the sofas inside.
```python
from inventree.stock import StockLocation
from inventree.stock import StockItem
...
## Create the stock locations. Leave the parent empty for top level hierarchy
Aisle3 = StockLocation.create(api, {'name':'Aisle 3','description':'Aisle for sofas','parent':''})
Shelve43 = StockLocation.create(api, {'name':'Shelve 43','description':'Shelve for sofas','parent':Aisle3.pk})
Box12 = StockLocation.create(api, {'name':'Box 12','description':'green box','parent':Shelve43.pk})
Box13 = StockLocation.create(api, {'name':'Box 13','description':'red box','parent':Shelve43.pk})
## Now fill them with items
Id1 = StockItem.create(api, { 'part': sofa.pk, 'quantity': 10, 'notes': 'new ones', 'location': Box12.pk, ‘status’:10 })
Id2 = StockItem.create(api, { 'part': sofa.pk, 'quantity': 3, 'notes': 'old ones', 'location': Box13.pk, ‘status’:55 })
```
Please recognize the different status flags. 10 means OK, 55 means damaged. We have the following choices:
* 10: OK
* 50: Attention needed
* 55: Damaged
* 60: Destroyed
* 65: Rejected
* 70: Lost
* 85: Returned
### Adding Manufacturers and Supplier
We can add manufacturers and suppliers to parts. We first need to create two companies, ACME (manufacturer) and X-Store (supplier).
```python
from inventree.company import Company
...
acme = Company.create(api, {
'name' : 'ACME',
'description':'A Company that makes everything',
'website':'https://www.acme.bla',
'is_customer':0,
'is_manufacturer':1,
'is_supplier':0
})
xstore = Company.create(api, {
'name' : 'X-Store',
'description':'A really cool online store',
'website':'https://www.xst.bla',
'is_customer':0,
'is_manufacturer':0,
'is_supplier':1
})
```
Please recognize the different flag settings for is_supplier and is_manufacturer. Now lets add those to our couch:
```python
from inventree.company import SupplierPart
...
SupplierPart.create(api,{
'part':couch.pk,
'supplier':xstore.pk,
'SKU':'some_code',
'link':'https://www.xst.bla/products/stock?...'
})
SupplierPart.create(api,{
'part':couch.pk,
'manufacturer':acme.pk,
'MPN':'Part code of the manufacturer'
})
```
### Stock Adjustments
Various stock adjustment actions can be performed as follows:
```python
from inventree.stock import StockItem, StockLocation
# Fetch item from the server
item = StockItem(api, pk=99)
# Count stock
item.countStock(500)
# Add stock to the item
item.addStock(15)
# Remove stock from the item
item.removeStock(25)
# Transfer partial quantity to another location
loc = StockLocation(api, pk=12)
item.transferStock(loc, quantity=50)
```
### Bulk Delete
Some database models support bulk delete operations, where multiple database entries can be deleted in a single API query.
```python
from inventree.stock import StockItem
# Delete all items in a particular category
StockItem.bulkDelete(api, filters={'category': 3})
```
### Upload Attachments
We have the possibility to upload attachments against a particular Part. We can use pdf for documents but also other files like 3D drawings or pictures. To do so we add the following commands:
```python
from inventree.part import PartAttachment
# The ID of the Part to attach the files to
part_id = 47
PartAttachment.upload(api, part_id, 'manual.pdf', comment='Datasheet')
PartAttachment.upload(api, part_id, 'sofa.dxf', comment='Drawing')
```
Alternatively, we can upload an attachment directly against the `Part` instance:
```python
from inventree.part import Part
part = Part(api, pk=47)
part.uploadAttachment('data.txt', comment='A data file')
```

149
docs/api/python/python.md Normal file
View File

@ -0,0 +1,149 @@
---
title: Python Interface
---
## Python Module
A [Python module](https://github.com/inventree/inventree-python) is provided for rapid development of third party scripts or applications using the REST API. The python module handles authentication and API transactions, providing an extremely clean interface for interacting with and manipulating database data.
### Features
- Automatic authentication management using token-based authentication
- Pythonic data access
- Native file uploads
- Powerful functions for accessing related model data
### Installation
The inventree python interface can be easily installed via the [PIP package manager](https://pypi.org/project/inventree/):
```
pip3 install inventree
```
!!! tip "Upgrading"
To upgrade to the latest version, run `pip install --upgrade inventree`
Alternatively, it can downloaded and installed from source, from [GitHub](https://github.com/inventree/inventree-python).
### Authentication
Authentication against an InvenTree server is simple:
#### Basic Auth
Connect using your username/password as follows:
```python
from inventree.api import InvenTreeAPI
SERVER_ADDRESS = 'http://127.0.0.1:8000'
MY_USERNAME = 'not_my_real_username'
MY_PASSWORD = 'not_my_real_password'
api = InvenTreeAPI(SERVER_ADDRESS, username=MY_USERNAME, password=MY_PASSWORD)
```
#### Token Auth
Alternatively, if you already have an access token:
```python
api = InvenTreeAPI(SERVER_ADDRESS, token=MY_TOKEN)
```
#### Environment Variables
Authentication variables can also be set using environment variables:
- `INVENTREE_API_HOST`
- `INVENTREE_API_USERNAME`
- `INVENTREE_API_PASSWORD`
- `INVENTREE_API_TOKEN`
And simply connect as follows:
```python
api = InvenTreeAPI()
```
### Retrieving Data
Once a connection is established to the InvenTree server, querying individual items is simple.
#### Single Item
If the primary-key of an object is already known, retrieving it from the database is performed as follows:
```python
from inventree.part import PartCategory
category = PartCatgory(api, 10)
```
#### Multiple Items
Database items can be queried by using the `list` method for the given class. Note that arbitrary filter parameters can be applied (as specified by the [InvenTree API](../api.md)) to filter the returned results.
```python
from inventree.part import Part
from inventree.stock import StockItem
parts = Part.list(api, category=10, assembly=True)
items = StockItem.list(api, location=4, part=24)
```
The `items` variable above provides a list of `StockItem` objects.
### Item Attributes
The available model attributes are determined by introspecting [API metadata](../metadata.md). To view the fields (attributes) availabel for a given database model type within the python interface, use the `fieldNames` and `fieldInfo` methods, as below:
```python
from inventree.api import InvenTreeAPI
from inventree.part import Part
api = InvenTreeAPI("http://localhost:8000", username="admin", password="inventree")
fields = Part.fieldNames(api)
for field in Part.fieldNames(api):
print(field, '->', Part.fieldInfo(field, api))
```
```
active -> {'type': 'boolean', 'required': True, 'read_only': False, 'label': 'Active', 'help_text': 'Is this part active?', 'default': True, 'max_length': None}
allocated_to_build_orders -> {'type': 'float', 'required': True, 'read_only': True, 'label': 'Allocated to build orders'}
allocated_to_sales_orders -> {'type': 'float', 'required': True, 'read_only': True, 'label': 'Allocated to sales orders'}
assembly -> {'type': 'boolean', 'required': True, 'read_only': False, 'label': 'Assembly', 'help_text': 'Can this part be built from other parts?', 'default': False, 'max_length': None}
category -> {'type': 'related field', 'required': True, 'read_only': False, 'label': 'Category', 'model': 'partcategory', 'api_url': '/api/part/category/', 'filters': {}, 'help_text': 'Part category', 'max_length': None}
component -> {'type': 'boolean', 'required': True, 'read_only': False, 'label': 'Component', 'help_text': 'Can this part be used to build other parts?', 'default': True, 'max_length': None}
default_expiry -> {'type': 'integer', 'required': True, 'read_only': False, 'label': 'Default Expiry', 'help_text': 'Expiry time (in days) for stock items of this part', 'min_value': 0, 'max_value': 2147483647, 'default': 0, 'max_length': None}
...
variant_stock -> {'type': 'float', 'required': True, 'read_only': True, 'label': 'Variant stock'}
```
### Item Methods
Once an object has been retrieved from the database, its related objects can be returned with the provided helper methods:
```python
part = Part(api, 25)
stock_items = part.getStockItems()
```
Some classes also have helper functions for performing certain actions, such as uploading file attachments or test results:
```python
stock_item = StockItem(api, 1001)
stock_item.uploadTestResult("Firmware", True, value="0x12345678", attachment="device_firmware.bin")
```
#### Discovering Methods
You can determine the available methods by either [reading the source code](https://github.com/inventree/inventree-python) or using the `dir()` function in an interactive terminal.
### Further Reading
The [InvenTree Python Interface](https://github.com/inventree/inventree-python) is open source, and well documented. The best way to learn is to read through the source code and try for yourself!