Cookbutler RESTful Web-service Documentation

# Start

API to receive recipes and recipe data.

# Get API key

Um diese API in vollem Umfang verwenden zu können, benötigst du einen API Schlüssel. Wie du an diesen kommst, erfährst du hier.

# Basic instructions

Bevor du mit den Methoden beginnst, lies dir bitte die Grundeinweisungen durch.

Bei dieser Dokumentation, handelt es sich um eine REST API Dokumentation. In der Regel verarbeiten wir GET und POST Anfragen. Unterschiede kannst du den Methoden entnehmen. Die Anfragen sind Plattform unabhängig. Ob du PHP, Python oder eine andere Skript-Sprache verwendest, spielt für uns keine Rolle. Alle Rückgaben sind im JSON Format. Als Charset verwendet wir UTF-8 und Uhrzeiten sind in der Zeitzone UTC.

API Endpoint: https://api.cookbutler.com/
Die Methoden werden per URI an den Endpoint angehängt.

Jede Anfrage und jede Antwort enthalten Header-Informationen. Manche dieser sind Pflicht, wie z.B. der User-Agent. Andere wiederum Optional. Hier eine Liste der Header-Daten für den Request und den Response:

Liste der akzeptierten Anfrage-Header
Name Value Description
Accept-Encoding
optional
Accepted:
  • gzip

Komprimiert die zu übertragenden Daten. Der Datentransfer kann aufgrund der kleineren Datengröße schneller durchgeführt werden.

Accept-Version
optional
Sample: v1

Zu verwendende Methoden-Version.

Jeder Methode hat seine eigene Version. Wenn nicht angegeben, wird immer die aktuellste verwenden.

Authorization
optional
Bearer {YOUR-JWT-TOKEN}

Enthält die Authorisierungs-Daten und Methoden-Parameter.

Alternativ kann JWT-Token auch mittels GET- oder POST-Parameter "jwt_token" mitgeschickt werden. Wir empfehlen aber den Authorization-Header zu verwenden.

Wie der JWT-Token erstellt wird, erfahrt ihr hier.

Content-Type
optional
Accepted:
  • application/json

Der Content-Type gibt an in welchen Format ihr uns eure Anfrage schickt.

Da wir alle Methoden-Parameter im JWT-Token haben, wird lediglich bei der Methode POST die Angabe von Content-Type benötigt.

User-Agent
Required
Sample: "Your Projectname/v1.0"

Wiki

Liste der mitgelieferten Antwort-Header
Name Value Description
X-API-Version Sample: v1

Aktuell verwendete Version der Methode.

X-API-Last-Version Sample: v1.1

Falls du nicht die aktuellste Version verwendest, wird dir hierüber mitgeteilt, dass es eine neuere Version dieser Methode gibt.

Falls du bereits die aktuellste Version verwendest, wird dir diese Angabe nicht mit geschickt.

X-RateLimit-Limit Sample: 60

Maximale Anzahl Anfragen, welche dir pro Minute zur Verfügung stehen.

X-RateLimit-Remaining Sample: 50

Noch verfügbare Anzahl an Anfragen bevor dein Client für den Rest des Zeitfensters gesperrt wird.

# Example

Request:
curl -X GET https://api.cookbutler.com/recipes/get-languages \
--header "User-Agent: Sample cURL Request" \
--header "Authorization: Bearer {YOUR-JWT-TOKEN}" \
--output -
Response:
200 Ok
{ "status": "ok", "data": { "total": 1, "languages": { "de-de": "de-de" } } }

# JWT Token

Zur Authorisierung einer Anfrage verwenden wir JWT. Für mehr Informationen über JWT, schaue zuerst auf jwt.io.

# Folgende Algorithmen werden von uns unterstützt:

  • HS256
  • HS384
  • HS512

# Payload

Der Payload enthält deinen API Schlüssel, die Methoden-Parameter und einen Zeitstempel, welchen eine Anfrage nur temporär gültig macht. Weitere Parameter, wie z.B. "jti" sind Optional und werden von uns nicht ausgewertet.

Wichtig: Die Methoden-Parameter können alternativ auch als POST-Parameter, z.B. URL-Encoded oder direkt als JSON-String angehängt werden. Siehe dazu das cURL-Beispiel.

Liste der verwendeten Payload-Parameter.

Name Description
api_key
Required / string

Dein API Schlüssel durch den wir deine Anwendung authentifizieren können.

iat
Required / integer

Issues At
Wir verwenden die Zeitzone UTC. Bitte achte beim Erstellen des iat-Wertes darauf.

Für weitere Informationen schaue bitte hier.

param
Required / array

Enthält die Methoden-Parameter.

# Examples

$algo = "HS256";
$header = ["typ"=>"JWT","alg"=>$algo];
$header = base64UrlEncode(json_encode($header)); # base64UrlEncode() is url safe base64_encode()


$iat_time = time(); # please note that we use the time zone UTC
$param = []; # params for methods
$payload = ["iat"=>$iat_time,"api_key"=>"{YOUR-API-KEY}","param"=>$param];
$payload = base64UrlEncode(json_encode($payload));


$signature = base64UrlEncode(hash_hmac($algo, $header . "." . $payload, "{YOUR-API-SECRET}", true));
$jwt_token = $header . "." . $payload . "." . $signature;
curl --location --request POST '{API-ENDPOINT}' \
--header 'User-Agent: xxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR-JWT-TOKEN}' \
--data-raw '{JSON-DATA}'

# Error Handling

Liste der Status-Codes welche wir verwenden. Für eine genauere Beschreibung, schaue dir die HTTP Statuscodes auf Wikipedia an.

Code Description
200 OK

Standard response for successful requests.

400 Bad Request

The request cannot be fulfilled due to bad syntax, as sample missing required parameter or wrong type of parameter.

401 Unauthorized

Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.

403 Forbidden

The request was valid, but you are not authorized to call this resource.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

405 Method Not Allowed

The request method is not supported for the requested resource.

412 Precondition Failed

If you send a request with missing header informations like "User-Agent".

500 Internal Server Error

A generic error message, given when no more specific message is suitable, in this case please open a support request.

501 Not Implemented

The server either does not recognize the request method.

# Example

Request:
GET https://api.cookbutler.com/recipes/get-languages
Response:
401 Unauthorized
{ "status": "error", "error": "Authorization was not found" }