An OpenAPI specification for the MagicBell API.

MagicBell

Last update: Dec 15, 2022

Related tags

Learning resource openapi

Overview

MagicBell's OpenAPI Specification

This repository contains OpenAPI specifications for the MagicBell REST API.

Changelog

Files can be found in the /spec directory:

openapi.json: OpenAPI 3.0 spec matching the public MagicBell API.
postman.json Postman 2.1.0 spec matching the public MagicBell API.

Vendor Extensions

The specification ships with a few vendor-specific fields to help represent information in ways that are difficult or unsupported in OpenAPI by default.

x-beta

MethodObjects can contain an x-beta: true property to indicate that the method is in beta or for other reasons unreleased. While you may be able to query them, they are unsupported and might be changed or even removed without notice.

{
  "paths": {
    "/easter-eggs": {
      "get": {
        "x-beta": true
      }
    }
  }
}

Postman

You'll find out postman collection at /spec/postman.json. To use it, import it in postman by clicking import in postman, and then dragging our json file onto that dialog.

Development

Run the test suite:

# clone the repo
git clone [email protected]:magicbell-io/openapi.git
cd openapi

# install dependencies
yarn

# validate the current spec
yarn validate

Code Quality

We're using pre-commit hooks to maintain consistency in code style for scripts in /scripts, and to verify that the openapi spec is valid according to openapi schemas. Please keep them enabled.

Comments

chore: scope vercel docs publications / preview urls to changes in /docs only

Vercel should only trigger docs previews and builds when changes affect /docs. It makes no sense to rebuild docs if it hasn't changed, or to post a 'preview url' to an openapi spec that doesn't affect docs.

Note, that's also the point that complicates it a bit. As the spec serves as input to partially generate our docs, changes outside of the /docs folder might affect that docs app. We need to think this trough.

We can achieve this using vercel "ignored build step"

issue separated from #14
project:docs meta

opened by smeijer 4
GitHub discussions links
Single commits can be reviewed independently:

~~to in PageLink is now required~~ (reverted because of a type error)

External links in left nav are marked with an icon (see image below)

Links to Slack replaced with links to GH Discussions (at the org level)

Explain that Slack is for power users
opened by 3v0k4 4
docs: preview urls should auto redirect to /docs
On each PR, Vercel deploys a preview. There are a couple of problems with that:

We don't need a preview if the change happens outside of /docs

The deployment doesn't work: when I click on "View deployment" I see the error below

project:docs meta
opened by 3v0k4 4
Move in examples repositories
Nota bene: merge #9 first and update base branch of this PR from readme to main.

Move the 3 example repositories into this monorepo (i.e., moved folders into examples/ and removed .git/ for each):

https://github.com/magicbell-io/react-native-demo

https://github.com/magicbell-io/react-native-notifications-example

https://github.com/magicbell-io/gatsby-example

I'm creating a PR in each of the above to replace the README with a link to this monorepo. I assume we want to make them public archives for the time being and remove them later to avoid breaking any links that could be out there).
opened by 3v0k4 4
Improve Nav & Content - December 2022
Change description

Updates to the navigation and content to improve the experience of first time visitors.

Type of change

[ ] Bug (fixes an issue)

[x] Enhancement (adds functionality)

Related issues

Fix #1

Checklists

Development

[ ] Lint rules pass locally

[ ] Application changes have been tested thoroughly

[ ] Automated tests covering modified code pass

Code review

[ ] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable
opened by unamashana 3
Use Algolia search indexes based on Vercel environments
Change description

Pick search indexes based on the Vercel env. This ensures the index is in sync with the deployed env, and there are no four-oh-fours!

Type of change

[x] Bug (fixes an issue)

[ ] Enhancement (adds functionality)

Related issues

Checklists

Development

[x] Lint rules pass locally

[x] Application changes have been tested thoroughly

[ ] Automated tests covering modified code pass

Code review

[x] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable

docs
opened by unamashana 3
fix(docs): ensure create-a-user link points to the correct section
Change description

Two of the internal links are not named correctly - create users API at https://www.magicbell.com/docs/compose#recipients users API endpoints at https://www.magicbell.com/docs/segments#setting-custom-attributes

They direct to the correct webpage but doesn't scroll to the appropriate location, thus causing a bad user experience.

Here's a GIF of the issue:

It's worth discussing if we can lint the broken links with an ESLint plugin. I have never written an ESLint plugin before but I'd assume for most of the documentation we have we could determine if a link is broken with static analysis, I don't think we might soon encounter a case where we are injecting links dynamically.

Type of change

[x] Bug (fixes an issue)

[ ] Enhancement (adds functionality)

Checklists

Development

[ ] Lint rules pass locally

[ ] Application changes have been tested thoroughly

[ ] Automated tests covering modified code pass

Code review

[ ] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable
opened by hoppercomplex 3
Add Dark Magic Visual Studio Code Theme
Change description

Added Visual Studio Code Color Theme

Type of change

[ ] Bug (fixes an issue)

[x] Enhancement (adds functionality)

Checklists

Development

[ ] Lint rules pass locally

[ ] Application changes have been tested thoroughly

[ ] Automated tests covering modified code pass

Code review

[ ] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable
opened by hoppercomplex 3
fix(docs): correct authentication page metadata
Change description

Before:

docs/api-authentication.mdx

--- title: REST API Reference subtitle: Explore the MagicBell REST API ---

After:

docs/api-authentication.mdx

--- title: Authentication subtitle: Learn how to use Authentication in your MagicBell Project ---

Type of change

[x] Bug (fixes an issue)

[ ] Enhancement (adds functionality)

Related issues

Fix #1

Checklists

Development

[ ] Lint rules pass locally

[ ] Application changes have been tested thoroughly

[ ] Automated tests covering modified code pass

Code review

[ ] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable
opened by hoppercomplex 1
fix: redirect idempotent-requests to section on overview page
Change description

Redirect https://magicbell.com/docs/rest-api/idempotent-requests to https://magicbell.com/docs/rest-api/overview#idempotent-requests

Type of change

[x] Bug (fixes an issue)

[ ] Enhancement (adds functionality)

Checklists

Development

[x] Lint rules pass locally

[x] Application changes have been tested thoroughly

[x] Automated tests covering modified code pass

Code review

[ ] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable
opened by smeijer 1
Updates to the API sections of the docs
Change description

Extracts authentication to its own page

Removes references to Postman and adds a download link for OpenAPI

Removes some other links - changelog, roadmap. We will be linking these to the GitHub repo shortly.

Type of change

[x] Bug (fixes an issue)

[x] Enhancement (adds functionality)

Related issues

Checklists

Development

[ ] Lint rules pass locally

[ ] Application changes have been tested thoroughly

[ ] Automated tests covering modified code pass

Code review

[ ] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable
opened by unamashana 1
docs/openapi: markdown in property's description is not rendered
Repro steps

visit https://www.magicbell.com/docs/rest-api/reference#create-notifications

notice the following:

Users to send the notification to. You can specify up to 1000 users in the request body or use [matches](https://www.magicbell.com/docs/segments#how-to-create-segments-using-the-api) to send a notification to any number of users.

Context

Markdown (CommonMark) is supported in that position by the OpenApi specs:

description - CommonMark syntax MAY be used for rich text representation.

Proposed solution

Investigate the code that renders the REST API Reference.
docs
opened by 3v0k4 0
feat: upgrade navigation
Change description

Upgrades the existing Navigation to a new one.

Features

[x] Sections – separated by borders, contains link/pages and may contain a heading on top of them.

[x] Grouped Links – links grouped together that can be collapsed or opened

[x] Pages – update state of navigation to display the subpage

[x] Subpage Heading and Back Button

[ ] Search

Type of change

[ ] Bug (fixes an issue)

[x] Enhancement (adds functionality)

Checklists

Development

[ ] Lint rules pass locally

[ ] Application changes have been tested thoroughly

[x] Automated tests covering modified code pass

Code review

[ ] Pull request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary

[ ] "Ready for review" label attached and reviewers assigned

[ ] Changes have been reviewed by at least one other contributor

[ ] Pull request linked to task tracker where applicable
opened by hoppercomplex 2

`overrides.channels.email.action_url` does not work

The Channel Overrides documentation states that email.action_url should work. But, when I pass overrides.channels.email.action_url, the email notification uses the non-overridden action_url passed to POST /notifications.

Tested with both the default email provider (Ping) and Sendgrid.

Support ticket.

Repro steps:

add below email template
send below notification

email template

action_url: {{ notification.action_url }}

notification

curl https://api.magicbell.com/notifications \
  --request POST \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-MAGICBELL-API-SECRET: MY_API_SECRET' \
  --header 'X-MAGICBELL-API-KEY: MY_API_KEY' \
  --data '{
    "notification": {
        "title": "test overrides.channels.email.action_url",
        "content": "testcontent",
        "category": "announcement",
        "action_url": "https://magicbell.com/docs",
        "recipients": [{ "email": MY_EMAIL }],
        "overrides": {
          "channels": {
            "email": {
              "action_url": "https://example.com"
            }
          }
        }
    }
  }'

bug project:api

opened by 3v0k4 1

Owner

MagicBell

The notification inbox for web & mobile applications.

GitHub

Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

JavaScript-med-Ramverk-Laboration-3 Grupprojektet för kurserna Javascript med Ramverk och Agil Utveckling. Utvecklingsguide För information om hur utv

3 May 18, 2022

Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

4 May 3, 2022

Kurs-repo för kursen Webbserver och Databaser

Webbserver och databaser This repository is meant for CME students to access exercises and codealongs that happen throughout the course. I hope you wi

14 Jan 3, 2023

Draft specification for a proposed Array.fromAsync method in JavaScript.

Array.fromAsync for JavaScript ECMAScript Stage-1 Proposal. J. S. Choi, 2021. Specification available Polyfill available Why an Array.fromAsync method

126 Dec 14, 2022

An example of implementation of the Veriifiable Presentation Generation Service specification.

Verifiable Presentation Generation Service A plugin-based service that allows issuers to render verifiable presentations from templates, and store it

5 Nov 16, 2022

REST API complete test suite using openapi.json

Openapi Test Suite Objective This package aims to solve the following two problems: Maintenance is a big problem to solve in any test suite. As the AP

21 Nov 3, 2022

Quickly bootstrap your next TypeScript REST API project. Node 16+, auto OpenAPI, Prettier+ESLint, Jest

REST API template with autogenerated OpenAPI Quickly bootstrap your next TypeScript REST API project with the most up to date template. Included a sam

6 Oct 1, 2022

Example auto-generated OpenAPI client library and an accompanying example Angular app.

To utilize this demo Head into petstore_frontend\petes_pets Run npm install Go to frontend_client_lib\out Run npm install Head back into petstore_fron

1 Jan 21, 2022

OpenAPI (Swagger) module for Nest framework (node.js) :earth_americas:

A progressive Node.js framework for building efficient and scalable server-side applications. Description OpenAPI (Swagger) module for Nest. Installat

1.3k Jan 6, 2023

OpenAPI support for tRPC 🧩

trpc-openapi OpenAPI support for tRPC ?? Easy REST endpoints for your tRPC procedures. Perfect for incremental adoption. OpenAPI version 3.0.3. Usage

841 Jan 9, 2023

Generate a zodios (typescript http client with zod validation) from an OpenAPI spec (json/yaml)

openapi-zod-client Generates a zodios (typescript http client with zod validation) from a (json/yaml) OpenAPI spec (or just use the generated schemas/

104 Jan 4, 2023

A Weather API project inspired by The Ultimate API Challenge / Weather API.

Weather API Project A Weather API project inspired by The Ultimate API Challenge / Weather API. Tech Stack: React.js Tailwind Axios Inspiration The Pr

1 Dec 29, 2021

This project is built with JavaScript, Webpack, HTML & CSS, Leaderboard api. When user clicks on Refresh button it hits the api and responds with the data, The user can also post data to the api

leaderboad Description the project. this project is about the leaderboad i did during Microverse to build a website for adding Data to the API and fet

4 May 30, 2022

An OpenAPI specification for the MagicBell API.

Related tags

Overview

MagicBell's OpenAPI Specification

Vendor Extensions

x-beta

Postman

Development

Code Quality

Comments

Change description

Type of change

Related issues

Checklists

Development

Code review

Change description

Type of change

Related issues

Checklists

Development

Code review

Change description

Type of change

Checklists

Development

Code review

Change description

Type of change

Checklists

Development

Code review

Change description

Before:

After:

Type of change

Related issues

Checklists

Development

Code review

Change description

Type of change

Checklists

Development

Code review

Change description

Type of change

Related issues

Checklists

Development

Code review

Repro steps

Context

Proposed solution

Change description

Features

Type of change

Checklists

Development

Code review

Repro steps:

Owner

MagicBell

Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Kurs-repo för kursen Webbserver och Databaser

Draft specification for a proposed Array.fromAsync method in JavaScript.

An example of implementation of the Veriifiable Presentation Generation Service specification.

REST API complete test suite using openapi.json

Quickly bootstrap your next TypeScript REST API project. Node 16+, auto OpenAPI, Prettier+ESLint, Jest

Example auto-generated OpenAPI client library and an accompanying example Angular app.

OpenAPI (Swagger) module for Nest framework (node.js) :earth_americas:

OpenAPI support for tRPC 🧩

Generate a zodios (typescript http client with zod validation) from an OpenAPI spec (json/yaml)

A Weather API project inspired by The Ultimate API Challenge / Weather API.

This project is built with JavaScript, Webpack, HTML & CSS, Leaderboard api. When user clicks on Refresh button it hits the api and responds with the data, The user can also post data to the api

Unofficial API client for the Tidbyt API. Use this client to control Tidbyt devices and integrate with other services.

Webb-tracker-api - James Webb Space Telescope (JWST) tracking REST API

To-do-expressJS-api - An ExpressJS API, where you can create your own To-Do's

Base-mock-api - Repo to storage my fake api's to use in my 2022 projects.