REST-API for kivitendo

This project aims to add a http-basic protected REST-API to kivitendo.

The following models are included:

rest_api model	kivitendo database tables
Customer	customer
Contact	contacts
Shipping	shipto
TaxZone	tax_zones
Currency	currencies
Order	oe
Orderitem	orderitems
Product	parts
Category	partsgroup
PaymentTerms	payment_terms

Requirements

kivitendo ~> 3.5.1
Ruby >= 3.0.x
Bundler ~> 2.4.21
Puma >= 6.4.0
libpq-dev (on Debian)

Installation

Ensure that you have at least the ruby 2.3.x installed on your system. On a Mac, Linux, Solaris or any other Unix systems we highly recommend you to use rvm, the ruby version manager. With rvm upgrading a ruby version is without pain! To learn more about rvm please visit: http://rvm.io.

rvm install ruby-3.0.2
rvm use ruby-3.0.2@kivitendo-rest-api --create
rvm @global do gem install bundler

To get the application started run the following commands in a console:

  git clone https://github.com/jfqd/kivitendo_rest_api.git
  cd kivitendo_rest_api
  export RAILS_ENV=production
  bundle install --path vendor/bundle --without development test

Before starting the webserver we need to create a secret, set the http-basic credentials and the database-url.

  # remove secrets-files
  rm config/secrets.yml.enc
  rm config/secrets.yml.key
  
  # create a secret for the application
  bundle exec rails secret

  # and copy it into the secret.yml.enc
  # together with the http-basic
  # credentials and the database-url
  # see secrets.yml.bak for reference
  bundle exec rails secrets:setup
  bundle exec rails secrets:edit

  # start the webserver
  bundle exec passenger start -d
  
  # stop the webserver
  bundle exec passenger stop

Usage

The api is protected by http-basic. Do not forget to protect these secrets by using https! To do so remove the comments and change the value for the hostname in config/initializers/application_controller_renderer.rb

The default in- and output is in xml-format, but you can use json too. Just add .json to the end of the path.

All following samples will use xml as the exchange-format.

Get a list of all customers

curl -s -u "user:password" 127.0.0.1:3000/api/v1/customers

Get one customer

curl -s -u "user:password" 127.0.0.1:3000/api/v1/customers/1

Change customer

curl -s \
     -u "user:password" \
     -X PUT \
     -H 'Content-Type: application/xml' \
     127.0.0.1:3000/api/v1/customers/1 \
     -d '
<customer>
 <notes>a new note</notes>
</customer>
'

Create a new customer

curl -s \
     -u "user:password" \
     -X POST \
     -H 'Content-Type: application/xml' \
     127.0.0.1:3000/api/v1/customers \
     -d '
<customer>
  <name>New Company</name>
  <street>Teststraße 42</street>
  <zipcode>1000</zipcode>
  <city>Berlin</city>
  <country>Deutschland</country>
  <phone>030 42424242</phone>
  <fax>030 43434343</fax>
  <homepage>http://example.com</homepage>
  <email>piet@example.com</email>
  <ustid></ustid>
  <taxzone-id>4</taxzone-id>
  <currency-id>1</currency-id>
  <contacts>
    <contact>
      <gender>m</gender>
      <title>Dr.</title>
      <fist-name>Piet</fist-name>
      <last-name>Mustermann</last-name>
    </contact>
  </contacts>
  <shippings>
    <shipping>
      <company>New Company</company>
      <contact>Susanne Musterfrau</contact>
      <gender>f</gender>
      <street>Teststraße 42</street>
      <zipcode>1000</zipcode>
      <city>Berlin</city>
      <country>Deutschland</country>
    </shipping>
  </shippings>
</customer>
'

Delete a customer

curl -s \
     -u "user:password" \
     -X DELETE \
     127.0.0.1:3000/api/v1/customers/1

Get a list of all tax-zones

curl -s -u "user:password" 127.0.0.1:3000/api/v1/tax_zones

Get a list of all currencies

curl -s -u "user:password" 127.0.0.1:3000/api/v1/currencies

Get a list of all orders

curl -s -u "user:password" 127.0.0.1:3000/api/v1/orders

Get one order

curl -s -u "user:password" 127.0.0.1:3000/api/v1/orders/1

Create a new order

curl -s \
     -u "user:password" \
     -X POST \
     -H 'Content-Type: application/xml' \
     127.0.0.1:3000/api/v1/orders \
     -d '
<order>
  <order-number>4711</order-number>
  <customer-id>1</customer-id>
  <contact-id>1</contact-id>
  <gross-total>49.0</gross-total>
  <net-total>41.18</net-total>
  <taxincluded>false</taxincluded>
  <order-date>2017-10-21</order-date>
  <delivery-date>2017-10-21</delivery-date>
  <notes>&lt;p&gt;Leistungsdatum entspricht Lieferdatum.&lt;/p&gt;</notes>
  <payment-id>1</payment-id>
  <taxzone-id>4</taxzone-id>
  <currency-id>1</currency-id>
  <closed>false</closed>
  <orderitems>
    <orderitem>
      <position>1</position>
      <product-id>1</product-id>
      <description>Free cookies</description>
      <price>0.0</price>
      <discount>0.0</discount>
      <qty>1.0</qty>
      <unit>Stck</unit>
      <base-qty>1.0</base-qty>
    </orderitem>
    <orderitem>
      <position>2</position>
      <product-id>2</product-id>
      <description>wedding-cake</description>
      <price>41.18</price>
      <discount>0.0</discount>
      <qty>1.0</qty>
      <unit>Stck</unit>
      <base-qty>1.0</base-qty>
    </orderitem>
  </orderitems>
</order>
'

Get a list of all products

curl -s -u "user:password" 127.0.0.1:3000/api/v1/products

Get one product

curl -s -u "user:password" 127.0.0.1:3000/api/v1/products/1

Change product

curl -s \
     -u "user:password" \
     -X PUT \
     -H 'Content-Type: application/xml' \
     127.0.0.1:3000/api/v1/products/1 \
     -d '
<product>
 <description>Change description</description>
</product>
'

Get a list of all categories

curl -s -u "user:password" 127.0.0.1:3000/api/v1/categories

Get one category

curl -s -u "user:password" 127.0.0.1:3000/api/v1/categories/1

Change category

curl -s \
     -u "user:password" \
     -X PUT \
     -H 'Content-Type: application/xml' \
     127.0.0.1:3000/api/v1/categories/1 \
     -d '
<category>
 <name>New name</name>
</category>
'

Create a new category

curl -s \
     -u "user:password" \
     -X POST \
     -H 'Content-Type: application/xml' \
     127.0.0.1:3000/api/v1/categories \
     -d '
<category>
  <name>Housing</name>
</category>
'

Delete a category

curl -s \
     -u "user:password" \
     -X DELETE \
     127.0.0.1:3000/api/v1/categories/1

You get the idea, right?

Hosting

We use Phusion Passenger, but you can use thin, puma, unicorn or any other rack server as well.

/usr/local/bin/bundle exec /usr/bin/ruby bin/rails server -e production -d

Todo

add model validation
add tests

Name		Name	Last commit message	Last commit date
Latest commit History 130 Commits
app		app
bin		bin
config		config
db		db
lib		lib
log		log
public		public
test		test
tmp		tmp
vendor		vendor
.gitignore		.gitignore
.rvmrc		.rvmrc
CHANGELOG.md		CHANGELOG.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
config.ru		config.ru
version		version

License

jfqd/kivitendo_rest_api

Folders and files

Latest commit

History

Repository files navigation