WebMini API

Overview

Introduction

Welcome to the WebMini API Documentation. This website aims to provide developers with all information necessary to implement the WebMini API into their project. We structured the documentation into several chapters:

  • On this Overview page, we describe the general design of the API.
  • On the Authentication page, we explain how to access the API using various methods, including OAuth2.
  • On the Webhooks page, a general introduction to WebMini webhooks and how to handle their payload is given.
  • Since WebMini offers multiple services, each service has its own API documentation. See Service APIs for an overview.
  • Should you have any questions or need assistance, please do hesitate to contact us via the Help page.

Schema

All API access is over HTTPS. The basic access point is https://my.webmini.com/api/v1/. All data is sent and received as JSON.

$ curl -i https://my.webmini.com/api/v1/testservice/get

HTTP/1.1 200 OK
Cache-Control: max-age=0
Content-Security-Policy: frame-ancestors 'self'
Content-Type: application/json; charset=utf-8
Date: Tue, 20 Oct 2015 10:23:57 GMT
Expires: Tue, 20 Oct 2015 10:23:57 GMT
Server: Apache
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
Content-Length: 8
Connection: keep-alive

["test"]

All timestamps are returned in ISO-8601 format: YYYY-MM-DDTHH:MM:SSZ

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -i https://my.webmini.com/api/v1/testservice/get?parameter=value

HTTP/1.1 200 OK
...

["test with parameter"]

For POST and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json:

$ curl -i -d '{"parameter":"value"}' https://my.webmini.com/api/v1/testservice/post

HTTP/1.1 201 Created
...

["test with parameter"]

Rate Limiting

Unauthenticated Requests

You can make up to up to 60 unauthenticated requests per hour. Unauthenticated requests are associated with no user account, but your IP address.

Authenticated Requests

For requests using a Personal API Token or OAuth, you can make up to 1,000 requests per day by default. If you think your application needs a higher rate limit, please contact us.

Rate Limit HTTP Headers

You can check the returned HTTP headers of any API request to see your current rate limit status:

$ curl -i https://my.webmini.com/api/v1/testservice/get

HTTP/1.1 200 OK
...
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
...

The headers tell you everything you need to know about your current rate limit status:

Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make in the current rate limit window.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in ISO-8601 format. Only present when you reached the limit.

Reaching the Rate Limit

Once you go over the rate limit you will receive an error response:

$ curl -i https://my.webmini.com/api/v1/testservice/get

HTTP/1.1 429 Too Many Requests
...
X-RateLimit-Reset: 2015-10-20T13:00:00Z
...

{
	"message": "API rate limit exceeded.",
	"documentation_url": "http://developer.webmini.com/index/"
}

User Agent Required

All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. Please choose a value that allows us to contact you if there are problems, such as your email address, website URL, or WebMini customer ID.

Here’s an example:

User-Agent: MyWebsiteUrl.com

If you provide an invalid User-Agent header, you will receive a 403 Forbidden response:

$ curl -iH 'User-Agent: ' https://my.webmini.com/api/v1/testservice/get

HTTP/1.1 403 Forbidden
...

{
	"message": "Please make sure your request has an User-Agent header.",
	"documentation_url": "http://developer.webmini.com/index/"
}