librepcb / librepcb-api

Server-side implementation of the LibrePCB API

LibrePCB API

The API is implemented with Django REST Framework on Python 3.

Setup

Create a virtualenv:

python3 -m venv VIRTUAL

Export some environment variables:

echo 'export DJANGO_DEBUG=true' >> VIRTUAL/bin/activate
echo 'export DATABASE_URL=postgres:///librepcb-api' >> VIRTUAL/bin/activate

Enable virtualenv:

source VIRTUAL/bin/activate

Install dependencies:

pip install -r requirements.txt

Create a database:

createdb librepcb-api

Initialize database:

src/manage.py migrate

Create a superuser:

src/manage.py createsuperuser

Start the development server:

src/manage.py runserver

The server is now running on http://localhost:8000/.

License

GPLv3, see LICENSE file.

librepcb-api's Issues

Take application version into account when delivering a list of libraries

Currently the API response of /api/v1/libraries contains all available libraries, no matter what file version they have. So if you use an older application version (e.g. with file format v0.1), you also get libraries with a newer file format (e.g. v0.2). But the application can't open these libraries because of the changed file format.

So the client (i.e. the application) needs to specify its version when asking the server for libraries. I think we can do this by using HTTP headers, for example:

X-LibrePCB-AppVersion: 0.1
X-LibrePCB-AppGitHash: 0385957012d0a103fc56d08dd55fe0b7c466710f

With this information, the server can filter out incompatible libraries in its response.

@dbrgn Would you agree with that? Is this functionality supported by the Django REST Framework?

SMTP

@ubruhin can you send me valid SMTP credentials for the server?

Update json library objects

Current response for GET /api/v1/libraries/:

{
    "uuid": "d0ff7c29-ef27-468a-a90e-518083b3d8e4",
    "name": "Base",
    "url": "git://github.com/librepcb-libraries/base",
    "publisher": {
        "name": "LibrePCB"
    },
    "dependencies": [
        "5a27a376-f1d9-4fac-a695-ef64d7c7012c"
    ]
}

Issues:

1. Missing multilingual support
2. Missing attributes: format_version, version, author, deprecated, download_url, description, keywords, image
3. Attribute publisher is no longer required

New json notation (proposal):

{
    "uuid": "d0ff7c29-ef27-468a-a90e-518083b3d8e4",
    "format_version": "0.1",
    "version": "0.0.1",
    "author": "LibrePCB",
    "deprecated": false,
    "url": "https://github.com/LibrePCB-Libraries/LibrePCB_Base.lplib",
    "download_url": "https://github.com/LibrePCB-Libraries/LibrePCB_Base.lplib/archive/master.zip",
    "image": "????",
    "name": {
        "en_US": "LibrePCB Base"
    },
    "description": {
        "en_US": "Official LibrePCB Base Library"
    },
    "keywords": {
        "en_US": ""
    },
    "dependencies": [
        "5a27a376-f1d9-4fac-a695-ef64d7c7012c"
    ]
}

Open questions:

• Libraries can have an image in their root directory, and this image should also be available through this API. In my opinion it would be best to use SVG images because they are only text files and thus suitable for version control. But how to deliver them with the API?
  • Compress the SVG file and put it as a Base64 encoded string into the library json object?
  • Convert the SVG to PNG and put it as a Base64 encoded string into the library json object?
  • Do not embed the image into the API response (e.g. only deliver an URL where the image can be downloaded separately)?
• Add the checksum of the library ZIP archives to the json object? This way we could make sure that the downloaded ZIP archive is equal to the one which was originally registered on the API server. If the hoster of a ZIP archive would silently replace an archive without registering this on our API server, LibrePCB would refuse to install that library.

TLS Certificates

To create the TLS certificate, I need to verify the domain.

@ubruhin I contacted you directly for details.

Use GitHub repository as server?

Just a stupid question:
Why not simply create a repository on GitHub, create a json file in it, and redirect https://api.librepcb.org/v1/libraries to that file? As we do not yet need to transfer data from the application to the server, this should be enough for the beginning.

Advantages:

• KISS - much less complexity!
• Transparency - Everyone can see how it works and who has changed which library and when.
• Everyone can ask for adding or updating a library just by creating a pull request (cool, isn't it?).
• We also need a way to provide library icons (*.png) - GitHub can do this too, just check in the icons.

Opinions?