iconify / api Goto Github PK

Iconify API script. Search engine for icons, provides icon data on demand for icon components, dynamically generates SVG.

License: MIT License

JavaScript 0.12% Dockerfile 1.04% Shell 0.76% TypeScript 98.09%

api icons svg

api's Introduction

Iconify API

This repository contains Iconify API script. It is a HTTP server, written in Node.js that:

Provides icon data, used by icon components that load icon data on demand (instead of bundling thousands of icons).
Generates SVG, which you can link to in HTML or stylesheet.
Provides search engine for hosted icons, which can be used by icon pickers.

NPM Package

This package is also available at NPM, allowing using API code in custom wrappers.

NPM package contains only compiled files, to build custom Docker image you need to use source files from Git repository, not NPM package.

Docker

To build a Docker image, run ./docker.sh.

If you want to customise config, fork this repo, customise source code, then build Docker image and deploy API.

To run a Docker image, run docker run -d -p 3000:3000 iconify/api (change first 3000 to port you want to run API on).

NPM commands for working with Docker images:

npm run docker:build - builds Docker image.
npm run docker:start - starts Docker container on port 3000.
npm run docker:stop - stops all Iconify API Docker containers.
npm run docker:cleanup - removes all unused Iconify API Docker containers.

There is no command to remove unused images because of Docker limitations. You need to do it manually from Docker Desktop or command line.

How to use it

First, you need to install NPM dependencies and run build script:

npm install
npm run build

Then you can start server:

npm run start

By default, server will:

Automatically load latest icons from @iconify/json.
Load custom icon sets from icons directory.
Serve data on port 3000.

You can customise API to:

Serve custom icon sets, loaded from various sources.
Run on different port.
Disable search engine if you do not need it, reducing memory usage.

Port and HTTPS

It is recommended that you do not run API on port 80. Server can handle pretty much anything, but it is still not as good as a dedicated solution such as nginx.

Run API on obscure port, hidden from outside world with firewall rules, use nginx as reverse proxy.

HTTPS is not supported. It is a very resource intensive process, better handled by a dedicated solution such as nginx. Use nginx to run as HTTP and HTTPS server, forward queries to API HTTP server on hidden port such as default port 3000.

Configuration

There are several ways to change configuration:

Editing files in src/config/, then rebuilding script. This is required for some advanced options, such as using API with custom icons.
Using environment variables, such as PORT=3100 npm run start.
Using .env file to store environment variables.

Env options

Options that can be changed with environment variables and their default values (you can find all of them in src/config/app.ts):

HOST=0.0.0.0: IP address or hostname HTTP server listens on.
PORT=3000: port HTTP server listens on.
ICONIFY_SOURCE=full: source for Iconify icon sets. Set to full to use @iconify/json package, split to use @iconify-json/* packages, none to use only custom icon sets.
REDIRECT_INDEX=https://iconify.design/: redirect for / route. API does not serve any pages, so index page redirects to main website.
STATUS_REGION=: custom text to add to /version route response. Iconify API is ran on network of servers, visitor is routed to closest server. It is used to tell which server user is connected to.
ENABLE_ICON_LISTS=true: enables /collections route that lists icon sets and /collection?prefix=whatever route to get list of icons. Used by icon pickers. Disable it if you are using API only to serve icon data.
ENABLE_SEARCH_ENGINE=true: enables /search route. Requires ENABLE_ICON_LISTS to be enabled.
ALLOW_FILTER_ICONS_BY_STYLE=true: allows searching for icons based on fill or stroke, such as adding style=fill to search query. This feature uses a bit of memory, so it can be disabled. Requires ENABLE_SEARCH_ENGINE to be enabled.

Memory management

By default, API will use memory management functions. It stores only recently used icons in memory, reducing memory usage. 000 If your API gets a lot of traffic (above 1k requests per minute), it is better to not use memory management. With such high number of queries, disc read/write operations might cause degraded performance. API can easily handle 10 times more traffic on a basic VPS if everything is in memory and can be accessed instantly.

See memory management in full API docs.

Updating icons

Icons are automatically updated when server starts.

In addition to that, API can update icon sets without restarting server.

To enable automatic update, you must set APP_UPDATE_SECRET environment variable. Without it, update will not work.

ALLOW_UPDATE=true: enables /update route.
UPDATE_REQUIRED_PARAM=secret: key from secret key/value pair. Cannot be empty.
APP_UPDATE_SECRET=: value from secret key/value pair. Cannot be empty.
UPDATE_THROTTLE=60: number of seconds to wait before running update.

To trigger icon sets update, open /update?foo=bar, where foo is value of UPDATE_REQUIRED_PARAM, bar is value of APP_UPDATE_SECRET.

Update will not be triggered immediately, it will be ran after UPDATE_THROTTLE seconds. This is done to prevent multiple checks when update is triggered several times in a row by something like GitHub hooks.

If update is triggered while update process is already running (as in, source was checked for update, but download is still in progress), another update check will be ran after currently running update ends.

Response to /update route is always the same, regardless of outcome. This is done to make it impossible to try to guess key/value pair or even see if route is enabled. To see actual result, you need to check console. Successful request and update process will be logged.

HTTP headers

By default, server sends the following HTTP headers:

Various CORS headers, allowing access from anywhere.
Cache headers to cache responses for 604800 seconds (7 days).

To change headers, edit httpHeaders variable in src/config/app.ts, then rebuild script.

Node vs PHP

Previous version of API was also available as PHP script. This has been discontinued. Node app performs much faster, can handle thousands of queries per second and uses less memory.

Full documentation

This file is basic.

Full documentation is available on Iconify documentation website.

Licence

Iconify API is licensed under MIT license.

SPDX-License-Identifier: MIT

This licence does not apply to icons hosted on API and files generated by API. You can host icons with any license, without any restrictions. Common decency applies, such as not hosting pirated versions of commercial icon sets (not sure why anyone would use commercial icon sets when so many excellent open source icon sets are available, but anyway...).

api's People

Contributors

Stargazers

Watchers

api's Issues

自定义的图标如何使用figma插件呢还有vscode插件如果能提供这样的功能就是最棒的

Multi cores

Hi!

Can you create a multi-core version for this node app?

I'm beginner in node and i want to run this app on my dedicated server with 8 cores.

Thanks !

MDI missing icons

I've set up this api and pointed my application to it. After doing so, it seems some of the icons from the MDI set that work when using the CDN api are no longer available. Examples are 'mdi:check-bold' and 'mdi:table-clock'. This persists even after specifying version 1.1.461 for @iconify/json in the optional dependencies.

Bumping version to non-beta?

Have been using your new and amazing TS-based API, it works great and just wanted to take the opportunity to thank you again.
What I wanted to ask is if you will mark it as a non-beta version soon (currently 3.0.0-beta.1)? 3.0.1 maybe?

[Suggestion] The `/update` API should ideally respond after the icon has been updated.

Hi, I want the response after Update complete, can you make this happen? thanks.

Or we can control this behavior by a parameter of the /update API.

[Bug] Issue about custom icons

I'm using the custom icons feature. when I put an icon collection file such as foo.json into the icons folder, It includes an icon bar: {body: 'xxx'}.

After that, When I use some APIs such as /collections?prefix=foo､ /collection?prefix=foo､ /foo.json?icons=bar, etc. They work fine.

But I deleted foo.json, and updated via the /update API. But It seems not updated. I can also receive the same responses via the APIs above. except /collections?prefix=foo, that's because it response is the icon info.

Expection

I hope it will return nothing after deleting the file.

Privatized deployment issues

When deploying privately, I found that the deployment instructions were not updated to the latest and some parameters could not be found. And how to implement hot update after running the package generated by npm run build command?

[Suggestion] Option to find bundles/sets based on provided icons

Loving the purpose of Iconify, but from what I can tell is there no real way to find a single Icon collection based on multiple provided SVGs.

My proposal is as follows:

The user could define multiple names (i.e. branding names) in a search field and Iconify would then return a list of collections that contain those icons.
The reason behind this is simple: Consistency.

While you could use icons of different collections within your project, be it a website, app or whatever, is there no denying that not every icon has the exact same style. Some collections may have other design practices (Or worst of all: None) and not every set you may want to use would have the icons you want to use, so you either have to use multiple sets with the risk of clashing designs, or spend a lot of time finding the one set that contains all the icons you want to use.

Having this search option could help a lot in narrowing down sets to those you would like to use.

I hope this all makes sense...

请问下用docker 怎么部署呢

Collaboration with jsDelivr

Would you consider collaboration with jsDelivr to publish your whole SVG library via their CDN? They may even provide a custom endpoint solution for this project: https://www.jsdelivr.com/oss-cdn

From the consumer perspective, it would be very nice to be able to use SVG files directly from a highly available CDN. I see api.iconify.design also provides SVG files but doesn't give that much confidence about the availability on high traffic. You may check bootstrap-icons as an example.

Support for setting host setting

In some environments it could be beneficial to only listen to a specific interface, such as localhost or a LAN instead of WAN interface.
Basically just a matter of adding the following:

// Create server
app.server.listen(app.config.port, app.config.host, () => {
	app.log('Listening on port ' + app.config.host + ':' + app.config.port);
});

and setting app.config.host = '0.0.0.0' by default to keep the current behavior intact.

Would you accept a pull-request for this?

update icon set/ icon in "/icons/*"

Guys, I would like to provide some modification related functionality to the custom icon in "https://github.com/iconify/api/tree/main/icons", such as

add a new icon set to it
delete an icon set
add a new icon to an icon set
Roughly like this

I came up with the following

PR to https://github.com/iconify/api
But I don't think that's a good idea, it breaks the /iconify/api streamlining.
use separate code for this. iconify/api to extend new routes.
use a new service to do this without modifying any of the behavior of /iconify/api.

Both iconify/api and the new service are eligible for the https://github.com/iconify/api/tree/main/icons directory.

I'd like to get some other inspiration. Thanks to all!

Add option to sort search results

Right now, the API seems to do no sorting at all; it just takes the complete list of icons, and filters out those which don't match the query and filter options, this leaves for some weird search results though.

You would expect if one searched "home", for all icons named "home" to come first, icons that are almost "home" (like "homes" or "add-home") to come second, and so forth, but this is not the case. Instead, the icons are ordered exactly as they are originally listed (presumably alphabetically, separated by icon sets). So, I think it would be useful to either add an option to sort the icons by relevancy or have that be the default.

I thought about doing this client side, but then you can run into cases where there might be an icon named "home" that is past the 999 icon mark (and is completely missed), even though that should be one of the first results.

Assuming you think this is a viable option, I could also attempt a pull request.

Setting to only cache recently requested icons in memory

Looking at running the Iconify API on an embedded platform with limited RAM. For this particular use case it would be great to be able to have caching only done for icons "recently" accessed. The goal is to provide the full set of icons, but knowing that only a few hundred will ever be used on each device, the memory footprint loading all of them is probably not the best.
The current solution has been to use the PHP version of the API, but since that version doesn't look like it's being maintained and everything else on this embedded platform is node.js based it would be nice to be able to use the node.js based API.
Is this a feature you have planned for the API server? If not, would you accept a pull-request for something like that?
Before spending the time developing this I wanted to check for interest in pull-requests since I don't want to maintain a separate fork.

I run it on docker map port to 6005. Navigated to https://iconify.design/

After I run the container. Open localhost:6005 redirected to https://iconify.design/

Why to npm

Just want to know 🧐.
Maybe "pnpm" has some problems.
c8d140c