# Bloodbath API This guide is intended to give you an overview of Bloodbath's capabilities, let you schedule events, and provide tips for how to use Bloodbath. ![](https://3110190463-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MkRmbYl9DJxiNaCmViE%2F-MkXtFnSrrRaw5rNcdqk%2F-MkXtZkS90YuTZpwH52_%2Fintroduction-a637c7fbd98e462d2f760ade9dea2fe1.svg?alt=media\&token=d1cd618e-e0fa-49d5-9d5a-96281423f7d5) # Acquire your API key Bloodbath APIs use API keys to authenticate requests. ## First things first Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. {% hint style="info" %} Authentication to the API is performed via [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). {% endhint %} All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without authentication will also fail. ## Where to find my API key? The easiest way to generate and get your API key is to [sign-up on Bloodbath](https://app.bloodbath.io/signup) via our dashboard. Once you've signed up you can go to the [settings section](https://app.bloodbath.io/settings) which will have your key. ![](https://3110190463-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MkRmbYl9DJxiNaCmViE%2F-MkRobgkQCPOJZngZf5d%2F-MkXst1Sjq3HlUWtcDpO%2FScreen_Shot_2021-06-05_at_7.53.52_PM.png?alt=media\&token=ca85ab9d-0985-4886-9360-37fa31545dd7) You can use this key to communicate will all Bloodbath APIs. ## How to check my API key is valid? To make sure your API key is valid and working, you can try the ping endpoint via cURL ``` curl \\ -H "Authorization: Bearer " # OK Response { "received_at": "2021-05-12T00:41:55.733297Z" } ``` # Schedule your first event Learn how to schedule your first event in less than 5 minutes Go to your terminal and write the cURL instruction down ``` curl \\ -H "Authorization: Bearer " \\ -d scheduled_for="" \\ -d headers="{}" \\ -d body="{test: test}" \\ -d method="post" \\ -d endpoint="" ``` You must change *\* with the key in your clipboard. Additionally, you have to **add a date in the future** for the event to be scheduled; change *\* by any date using the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, for example ``` 2021-05-01T00:00:00Z ``` You should receive the information of created event with its id as a response immediately. One good practice if you're using this within any codebase is to **store this id somewhere, which will allow you to find or cancel the event easily.** ![](https://3110190463-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MkRmbYl9DJxiNaCmViE%2F-MkXtndK6iBn18uvNiVL%2F-MkXttSqi5GkWhSNG0-5%2Fdummy-bloodbath-console_\(1\).gif?alt=media\&token=2b9c42d1-7a87-4391-b767-13c91ec48d66) ## Look it up through the dashboard Once you reach the date you previously set, the event will be triggered and sent to the endpoint. You can immediately [check the dashboard](https://app.bloodbath.io/events) ![In this example, we've scheduled 5 events to be dispatched at the same time](https://3110190463-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MkRmbYl9DJxiNaCmViE%2F-MkXtndK6iBn18uvNiVL%2F-MkXu4SJ5U9W17cygFvz%2FScreen_Shot_2021-06-05_at_9.12.04_PM.png?alt=media\&token=9a873b2d-f30b-4a02-91ee-734975b9b4c1) ### Check the details of your events You can access the details directly through the dashboard. But also through our REST or GraphQL API directly. ![](https://3110190463-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MkRmbYl9DJxiNaCmViE%2F-MkXuoUbabImPI6bkcaH%2F-MkXv9a5XoRA1uIQLQL2%2FScreen_Shot_2021-06-05_at_9.12.40_PM.png?alt=media\&token=d83c6980-3183-4867-8bf9-1014f5f3d550) A few states are obvious, but you may wonder what the enqueue, lock and dispatch are | **Name** | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | **Enqueued at** | Time at which the event is pulled from the database and a process is scheduled internally for future spawning | | **Locked at** | The process is being run, you can't cancel the event from this point forward | | **Dispatched at** | Bloodbath sent the payload over | ## Going further Congratulation, you went through the basics of Bloodbath. Using our REST API through cURL is a good first step, but **we provide much more than that**. You can use our GraphQL API or the different language libraries to write up scripts or adding our service to your codebase. {% hint style="info" %} If your **favorite language** isn't present in our libraries, **don't hesitate to** [**contact us**](mailto:support@bloodbath.io) and we'll gladly add it. {% endhint %} # Being on the beta release You're currently on an early release of Bloodbath. We are testing out scalability and still developing the base libraries used by the core. No worry, Bloodbath is already pretty stable, it's more about market fit and business model. Our team is still thinking this through. {% hint style="info" %} **You can enjoy our service without any limit whatsoever until we get this settled.** {% endhint %} # Working with REST The Bloodbath API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ## Prerequisite {% content-ref url="/pages/-MkXsUqmKJQVh5Cpqa7b" %} [Acquire your API key](/getting-started/acquire-your-api-key) {% endcontent-ref %} ## Get the list of events ``` curl \\ -H "Authorization: Bearer " # OK Response { "data": [ { "endpoint": "", "enqueued_at": null, "headers": "{}", "id": "226a9043-120e-49a5-a3ca-e942915020e4", "origin": "rest_api", "body": "{test: true}", "processed_at": null, "scheduled_for": "2021-05-09T00:04:34Z" }, { "endpoint": "", "enqueued_at": null, "headers": "{}", "id": "2d8e90be-4e3c-4236-8de9-9473b3143c26", "origin": "rest_api", "body": "{test: true}", "processed_at": null, "scheduled_for": "2021-05-09T00:04:36Z" }, ] } ``` ## Find a specific event ``` curl \\ -H "Authorization: Bearer " # OK Response { "data": { "endpoint": "", "enqueued_at": null, "headers": "{}", "id": "226a9043-120e-49a5-a3ca-e942915020e4", "origin": "rest_api", "body": "{test: true}", "processed_at": null, "scheduled_for": "2021-05-09T00:04:34Z" } } ``` ## Schedule a new event ``` curl \\ -H "Authorization: Bearer " \\ -d scheduled_for="2021-05-01T00:00:00Z" \\ -d headers="{}" \\ -d body="{test: test}" \\ -d method="post" \\ -d endpoint="" # OK Response { "data": { "endpoint": "", "enqueued_at": null, "headers": "{}", "id": "226a9043-120e-49a5-a3ca-e942915020e4", "origin": "rest_api", "body": "{hello:true}", "processed_at": null, "scheduled_for": "2021-05-09T00:04:34Z" } } ``` ## Cancel an existing event {% hint style="info" %} You can't cancel events that were already enqueued and/or processed {% endhint %} ``` curl \\ -H "Authorization: Bearer " \\ -X DELETE # OK Response { "data": null } ``` # Working with GraphQL Bloodbath proposes a powerful GraphQL API. It's the same API we use internally for developing our applications, most notably our own dashboard. We follow a [Relay style](https://relay.dev/) of schema. If you're new to GraphQL, Apollo has [resources for beginners](https://blog.apollographql.com/the-basics-of-graphql-in-5-links-9e1dc4cac055). [The official documentation](https://graphql.org/) is another good starting point. ## Prerequisite {% content-ref url="/pages/-MkXsUqmKJQVh5Cpqa7b" %} [Acquire your API key](/getting-started/acquire-your-api-key) {% endcontent-ref %} ## Endpoint Bloodbath's GraphQL endpoint is: ``` https://api.bloodbath.io/graphql ``` It supports introspection so you can query the whole schema. ## Authorization To start querying the endpoint, you must add the API key to your `authorization` headers. ``` { "headers": { "authorization": "Bearer " } } ``` ### Check your access Once you have the headers in place you can ping the GraphQL API ``` query ping { ping { receivedAt } } ``` It should respond with something like ``` { "data": { "ping": { "receivedAt": "2021-05-23T20:45:44.409594Z" } } } ``` ## Examples ### List events ``` query listEvents { listEvents(first: 5) { pageInfo { startCursor } edges { node { id eventId method lockedAt } } } } ``` {% hint style="info" %} You'll notice that a difference between id and eventId; we have a **Relay style schema.** It means we have to map a node id and the event id has to be put on the side. {% endhint %} ### Find an event ``` query findEvent{ findEvent( id: "f6596250-044b-4070-a256-31f0977ea4f3" ) { eventId scheduledFor } } ``` # What protocols can be used? Bloodbath currently supports HTTP(S) payloads to be transmitted to any endpoint. {% hint style="info" %} If you need another protocol to be supported, don't hesitate to contact us and we'll add it on our roadmap {% endhint %} # What's the maximum payload size? | Property | Maximum size | Reason | | -------- | ------------ | -------------------------- | | Headers | 50KB | Hard limit on HTTP headers | | Body | 1MB | Set by bloodbath | {% hint style="info" %} If you want to have a larger body size for your specific use, please [contact us](mailto:support@bloodbath.io) so we can set a specific limit for you. {% endhint %} # What's the correct format to build headers? The headers should be a valid JSON. You have to quote the keys and values and avoid spaces before the `:` character. In some clients, you may have to escape the double quotes like so ``` "{\\"valid\\": \\"json-format\\"}" ``` Upon receiving a bad JSON format, Bloodbath API will refuse adding your event and output a clear error. # Wrong format when sending my body over the REST API If you're using the REST API, you must be careful about the format you sent the body to. It should be strict JSON. ``` # GOOD "{\\"scheduled_for\\":\\"2021-05-25 15:35:41 -0500\\",\\"method\\":\\"post\\",\\"headers\\":{\\"Random-Header\\":\\"Something\\"},\\"body\\":\\"Random body\\",\\"endpoint\\":\\"\\"}" # BAD "{:scheduled_for=>2021-05-25 15:35:41.604712 -0500, :method=>:post, :headers=>{:\\"Random-Header\\"=>\\"Something\\"}, :body=>\\"Random body\\", :endpoint=>\\"\\"}" ``` If the JSON can't be decoded by the Bloodbath API, it'll throw an error.