Skip to content
FOSS JSON REST API for digital stores.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.gitignore
README.md

README.md

Niknak

Project Logo

FOSS JSON REST API for digital stores. The ultimate goal is to become the Wordpress of independent online sales.

This repository will include a reference implementation - Python server, client library, and test suite.

http://campadrenalin.github.io/Niknak

High-level architecture

Everything is pluggable

Authentication, media transformation, payment mechanisms, backend storage - Niknak is designed to be as agnostic as possible, so you can use it to build something that meets your needs, whether that's a very simple test instance running on localhost, or a set of production machines using every bell and whistle available.

Planned support

  • Authentication
    • Mozilla Persona (BrowserID)
    • Username/password
    • OAuth*
  • Payment
    • Bitcoin
    • Paypal
    • Ripple*
    • Stripe*
  • Storage
    • SQLite
    • PostGRE*
    • MariaDB/MySQL*
  • Cache layer
    • Redis*
    • Memcached*
  • Media transformation
    • PIL (The Python Image Library)
    • ffmpeg/avconv*
    • ImageMagick*

* Eventual support

Support for multiple currencies

This is baked in from the beginning. Most people will just want to set this to immediately convert to store currency, of course, but it's nice to have the general case covered.

Everything is done through, and built from, the API

Niknak is the glue that ties everything together. Your web frontend, your console clients, third-party infrastructure and more. All of it can talk to Niknak in a common "language," and anyone can write software that builds on Niknak, because Niknak is designed to be easy to build on.

The great thing about this is that nobody gets left out in the cold. Any feature, if it exists, is available through the API. Which means any external technology can be programmed to use it. No product gets special treatment - or the shaft.

Because Niknak is an open-source project and is designed to enforce modularity in your store design, you can have confidence knowing that the common base of your store is being continually battle-tested by a wide variety of use cases, and developers can enjoy the benefits of a clean, self-contained codebase.

I want to try Niknak!

Sorry, this is still in the design stages. It will be a long time before Niknak is powering any online stores. I appreciate your enthusiasm, though!

If you have questions, you can email them to philip@roaming-initiative.com. You may even have an effect on the direction and design of Niknak! I love to get outside opinions, and hear how people use (or plan to use) things I've worked on.

API

$root/

GET POST PUT DELETE
Responds with store metadata Set store metadata No action No action

Site metadata is a simple JSON object containing configuration and version information.

$root/users/

GET POST PUT DELETE
User statistics No action Create new user No action

User statistics are currently arbitrary, but may be standardized in the future.

User properties TBD.

$root/users/$uid

GET POST PUT DELETE
User properties Update user properties No action Delete user

User properties TBD.

$root/users/$uid/owned

GET POST PUT DELETE
List of products purchased by user No action No action No action

$root/products

GET POST PUT DELETE
List of products. Uses variables to filter and sort. No action Create new product. No action

$root/products/$product_id

GET POST PUT DELETE
Product properties Update product properties No action Delete product

Product properties TBD.

$root/payments

GET POST PUT DELETE
Payment statistics No action Create new payment No action

$root/payments/$payment_id

GET POST PUT DELETE
Payment properties Update payment properties Confirm payment Cancel payment

The properties you can update after confirmation are very limited - basically just the memo.

$root/specials

GET POST PUT DELETE
List all currently available and historical specials No action No action No action

Specials are things like "Buy one get one free." Unlike most things, they are ID'd by name. They are built into the system, and cannot be custom-defined without modifying the Niknak code, but may have any per-product parameters.

$root/specials/$special_name

GET POST PUT DELETE
Description of special, and list of products it currently applies to. No action No action No action

$root/purchases

GET POST PUT DELETE
Purchase statistics No action New purchase No action

A purchase associates a user, a total, a memo, and a list of [quantity, product_id, specials] tuples.

$root/purchases/$purchase_id

GET POST PUT DELETE
Purchase properties Update purchase properties Confirm purchase Cancel purchase

Purchase properties cannot be changed after confirmation, but the purchase may be canceled, with server-side logic to determine if the cancellation is successful. Cancelling a purchase reverts ownership of the products, and refunds the customer.

$root/tags

GET POST PUT DELETE
List of all available tags No action New tag No action

Listing includes shallow metadata for each tag (description, image URL, etc.)

$root/tags/$tag_name

GET POST PUT DELETE
Tag properties Update tag properties No action Delete tag

$root/permission

GET POST PUT DELETE
No action No action Create new permission No action

$root/permission/$permission_id

GET POST PUT DELETE
Return permission data Update permission data No action Revoke permission

Permissions have a few properties.

  • User ID
  • Type (read, write, or both)
  • Method
  • Object ID
  • Scope

Method is an HTTP method (i.e. "PUT") and Object ID is an API URL (i.e. "$root/users" or "$root/groups/*"). The asterisk is a wildcard for a range of non-/ characters.

Scope may be null, or a comma-separated list of property names (for restricting what properties can be seen or updated). Properties may have a " = somevalue" or " IN (value1,value2)" for further row filtering. For example, to give a daemon the ability to determine if a user has access to a service (for example, an MMO or a VPN), give the daemon a permission with Object ID "$root/users/*/owned", method "GET", type "read", and scope "product_id=72", where 72 is the ID of the service. If the daemon needs to see this data for multiple services, you could express this with multiple permissions, or a scope like "product_id IN (72, 40, 99)".

The term user ID is a bit disingenuous. All UIDs under 1000 (a configurable number) represent user groups. The two default groups are admin (0) and everyone (1). The admin group can be edited, the everyone group cannot. Thus, permissions with a UID < 1000 are group permissions.

$root/groups

GET POST PUT DELETE
List existing groups No action Create new group No action

A group list is a {"$id":"$groupname"} mapping.

$root/groups/$group_id

GET POST PUT DELETE
Return group metadata Update group metadata Add user to group Delete group

$root/groups/$group_id/$user_id

GET POST PUT DELETE
Return 'true' or 'false' No action No action Delete user from group

Can be GET-ed to determine if user is a member of a group. If 'false', response code must also be 404.

Something went wrong with that request. Please try again.