Entwicklung mit Ideanote

Vielen Dank für Ihr Interesse an der Entwicklung mit Ideanote!

Ideanote ist von Grund auf modular und flexibel aufgebaut, um eine Vielzahl von Anwendungsfällen im Bereich Innovation zu unterstützen. Mit unserer einfach integrierbaren REST-API können Sie individuelle Innovations-Workflows für Ihr Unternehmen erstellen – von der Erfassung von Ideen bis zur Verwaltung von Teams und zur Datensynchronisierung.

Einführung

Die Ideanote-API basiert auf REST. Unsere API verfügt über vorhersehbare, ressourcenorientierte URLs, gibt JSON-codierte Antworten zurück und verwendet standardisierte HTTP-Antwortcodes, Authentifizierung und Verben. Die API ist zustandslos – alle Anfragen werden anhand eines API-Tokens validiert.

Die API ist versioniert, um Rückwärtskompatibilität zu gewährleisten: Die aktuelle Version ist v1.

Die aktuelle Basis-URL der API lautet https://api.ideanote.io/v1/.

Beachten Sie, dass das URL-Abfrageparameterfeld für alle Endpunkte erforderlich ist.

Anwendungsfälle

Die Ideanote-API bietet eine leistungsstarke Auswahl an Tools, mit denen Sie Funktionen zur Ideenverwaltung in Ihre Geschäftsprozesse und bestehende Infrastruktur integrieren können.

Die Einsatzmöglichkeiten unserer API reichen von der tiefgreifenden Integration von Ideanote in eine von Ihnen entwickelte Anwendung bis hin zu einfacheren Anwendungsfällen wie dem Senden von Ideen an Ideanote oder der Synchronisierung von Daten zwischen Ideanote und einer anderen Anwendung.

Sehen Sie sich die folgenden Beispiele an:

Einreichung von Ideen: Erfassen Sie automatisch Ideen aus internen Kommunikationstools und virtuellen Besprechungen über die Ideanote-API und reichen Sie sie direkt bei Ideanote zur Bewertung ein.
Integration ins Projektmanagement: Überführen Sie genehmigte Ideen nahtlos mithilfe der Ideanote-API in umsetzbare Projekte, indem Sie Aufgaben oder Projekte in Projektmanagement-Tools wie Jira erstellen.
Feedback in der Anwendung: Leiten Sie Kundenfeedback aus Ihren Anwendungen mithilfe der API direkt an Ideanote weiter, um strukturierte, kundengesteuerte Innovation zu ermöglichen.
Business Intelligence: Extrahieren Sie Daten zu Ideeneinreichungen für BI-Analysen und erstellen Sie mit der Ideanote-API detaillierte Berichte zu Innovations-ROI, den besten Ideen und den Beiträgen von Mitarbeitenden.
Anerkennung von Mitarbeitenden: Verbinden Sie Ideanote mit HR-Systemen, um Mitarbeitende automatisch für ihren Beitrag zu erfolgreichen Ideen zu belohnen und so das Engagement zu steigern.
Einhaltung des Datenschutzes: Stellen Sie die Einhaltung von Datenschutzvorschriften sicher, indem Sie die API zur Verwaltung von Nutzerdaten verwenden. Dazu gehört auch, deaktivierte Nutzer in Ihrem zentralen Verzeichnis zu suchen, zu aktualisieren oder zu löschen.

Durch die Nutzung der Ideanote-API auf diese Weise können Sie ein stärker integriertes, effizienteres und ansprechenderes Innovationsökosystem für Ihr Unternehmen schaffen.

Grundlagen der REST-API

Die API von Ideanote ist eine REST-basierte Schnittstelle. Das bedeutet, dass Anwendungen Anfragen an die API stellen, indem sie über HTTPS auf bestimmte URLs zugreifen. Jede Anfrage ist ein einzelner, in sich abgeschlossener Vorgang.

Die Basis-URL für alle API-Aufrufe lautet https://api.ideanote.io/v1/. Um auf verschiedene Ressourcen zuzugreifen, werden dieser Basis-URL spezifische Pfade angehängt. Um beispielsweise Ideensammlungen aufzulisten, wird die URL um /v1/idea_collections erweitert.

Die Authentifizierung ist für die Verwendung der Ideanote API unerlässlich. Dazu muss ein Zugriffstoken im HTTP-Header als Authorization: Bearer YOUR_TOKEN enthalten sein. Dadurch wird ein sicherer Zugriff auf Ihre Workspace-Daten gewährleistet, der auf den Nutzer beschränkt ist, der das Zugriffstoken erstellt hat. Außerdem müssen alle API-Aufrufe einen Accept: application/json Header enthalten, der angibt, dass das Datenaustauschformat JSON ist, das einzige von der API unterstützte Format.

Die API ist um Ressourcen herum organisiert, die über die URL identifiziert und mithilfe von HTTP-Verben wie GET, POST, PUT und DELETE bearbeitet werden. Diese Verben geben an, welche Aktion Sie ausführen möchten, z. B. Abfragen, Hinzufügen, Aktualisieren oder Löschen.

Parameter spielen für die Funktionalität der API eine wichtige Rolle. Abfrageparameter geben Details für GET-Anfragen an, während Textkörperdaten für PUT- und POST-Anfragen verwendet werden. Dies ermöglicht differenzierte Interaktionen mit der API, etwa das Durchblättern von Ergebnissen oder das Aktualisieren bestimmter Ressourcendaten.

Die Fehlerbehandlung in der Ideanote API verwendet standardisierte HTTP-Statuscodes, um den Erfolg oder Misserfolg von Anfragen anzuzeigen. Zu den gängigen Codes gehören 200 für erfolgreiche Anfragen, 400 für fehlerhafte Anfragen, 429 für die Überschreitung von Nutzungslimits und 500 für interne Serverfehler.

Ideanote-Datenstruktur

Die Architektur von Ideanote ist darauf ausgelegt, die hierarchische und kollaborative Natur von Innovation in Unternehmen widerzuspiegeln. Diese Struktur unterstützt einen organisierten Ansatz zur Verwaltung von Ideen – von der Entstehung bis zur Umsetzung – in einem digitalen Workspace, der auf Effizienz ausgelegt ist.

Im Folgenden gehen wir auf die wichtigsten Komponenten der Datenstruktur von Ideanote ein, damit Entwickler die Plattform effektiv nutzen und sich darin zurechtfinden können.

Workspaces: Ein Workspace ist die oberste Ebene in Ideanote. Hier wird alles rund um Innovation an einem zentralen Ort für die Ideen des Unternehmens organisiert.

Abschnitte:Abschnitte unterteilen den Workspace in überschaubarere Bereiche, beispielsweise nach Abteilungen oder Themen. So lässt sich Innovation im Unternehmen leichter organisieren.

Ideensammlungen:In Ideensammlungen werden Ideen zu bestimmten Themen zusammengetragen. Sie umfassen Phasen, die eine Idee durchlaufen muss, und strukturieren so den Entwicklungsprozess von Anfang bis Ende.

Phasen und Ideen:Phasen sind die Schritte, die eine Idee innerhalb einer Sammlung von der Entstehung bis zum Abschluss durchläuft. Ideen sind dabei die grundlegenden Elemente: Nutzer bringen sie ein, und durch Kommentare, „Gefällt mir“-Angaben sowie den Fortschritt durch diese Phasen entwickeln sie sich weiter. Jede Idee basiert auf einem benutzerdefinierten Formular mit Ideenfeldern, die vom Unternehmen festgelegt werden. Je nach Kontext können für verschiedene Ideensammlungen unterschiedliche Formulare verwendet werden.

Nutzer, Teams und Berechtigungsstufen:Innerhalb eines Workspace sind Nutzer die Mitwirkenden und können zur Zusammenarbeit in Teams gruppiert werden. Nutzer haben Berechtigungsstufen wie Workspace Owner, Admin, Mitglied und Gast, die ihnen mehr oder weniger Zugriff auf Einstellungen, das Erstellen von Ideensammlungen und die Verwaltung von Inhalten gewähren.

Zugriff und Berechtigungen:Der Zugriff auf Ideensammlungen wird über Freigabeeinstellungen und nicht über Berechtigungsstufen verwaltet. Das bedeutet, dass die Möglichkeit eines Nutzers, Ideensammlungen zu sehen, Beiträge hinzuzufügen oder mit ihnen zu interagieren, davon abhängt, ob sie für den Nutzer oder sein Team freigegeben wurden. So können sich die richtigen Personen auf die relevanten Aufgaben konzentrieren.

Weitere Informationen zu Nutzerrängen und Berechtigungen finden Entwickler im Hilfe-Center von Ideanote.

API-Zugriff

Um mit der Ideanote API zu beginnen, müssen Sie in der Ideanote App unter Einstellungen > Konto > API-Token Ihr API-Zugriffstoken generieren.

Für den Zugriff benötigen Sie mindestens den Rang eines Admins. Jeder Nutzer hat über die API Zugriff auf die Entitäten und Daten, auf die er als Nutzer in der Ideanote App zugreifen kann.

Sie können mehrere API-Tokens für verschiedene Anwendungen verwenden und jedes einzelne bei Bedarf widerrufen.

Unsere APIs können von Kunden mit einem kostenpflichtigen Abonnement kostenlos genutzt werden.

Beispiele für API-Aufrufe

In diesem Tutorial erfahren Sie, wie Sie Ihren ersten API-Aufruf an die Ideanote API tätigen und eine Liste von Ideen aus einer Ideensammlung abrufen.

Schritt 1: Ideanote-API-Zugriffstoken generieren

Hier finden Sie eine Schritt-für-Schritt-Anleitung für die Autorisierung

Sie müssen dieses 43 Zeichen lange Token bei allen HTTPS-Anfragen an die Ideanote-API, mit denen Sie auf die in Ihrem Konto definierten Inhalte zugreifen, in einem Authorization-Header vom Typ Bearer Token übermitteln. Hier ein Beispiel für einen Authorization-Header:

Authorization: Bearer ea5b9e4********************

Schritt 2: Ideensammlungen über die API auflisten

Rufen Sie den Endpunkt für Ideensammlungen auf, um alle Ideensammlungen aufzulisten, auf die Ihr Nutzer Zugriff hat.

curl -X GET "https://api.ideanote.io/v1/idea_collections" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <API Token>"

Der obige Befehl gibt JSON in folgender Struktur zurück:

[
    {
        "id": "020166b4-8846-4896-b2ac-9074fd3a1b2c",
        "title": "Example Idea Collection",
        "question": "How might we improve the coffee?",
        "details": null,
        "stats": {
            "ideas": {
                "total": 3
            }
        },
        "cover": {
            "url": {
                "thumbnail": "https://uploads.staging.ideanote.dev/staging/v1/f985c93c-bcbd-e67f-31e5-d54f965a5fe1/download_original"
            }
        }
    }
]

Schritt 3: Eine Ideensammlung auswählen und Ideen auflisten

Rufen Sie den Endpunkt auf, um Ideen in einer bestimmten Ideensammlung aufzulisten. Im folgenden Beispiel wurde die ID im Format hier eingetragen. Außerdem enthält es URL-Parameter, mit denen Metadaten und Ideenfelder einschließlich Feldtiteln, Typen und Werten zurückgegeben werden.

curl -X GET "https://api.ideanote.io/v1/idea_collections/020166b4-8846-4896-b2ac-9074fd3a1b2c/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <API Token>"

Schritt 4: Die JSON-Antwort verarbeiten

Die HTTPS-Antwort enthält eine Liste von Ideen im JSON-Format.

Jedes Ideenfeld umfasst einen Titel und einen Wert. Wenn Sie nach bestimmten Inhalten suchen, beispielsweise nach der Beschreibung einer Idee, können Sie anhand des Titels nach der entsprechenden :id suchen und anschließend den Wert dieses Ideenfelds verarbeiten. Ideenfelder werden anhand ihrer ID aufgeführt, damit die API konsistent bleibt, auch wenn ein Ideenfeld in der Ideanote App umbenannt wird.

Die IDs der Ideenfelder können Sie vorab in der Ideanote App unter Formulare > Felder > ID kopieren ermitteln.

[
    {
        "id": "38494f31-4edc-414c-8320-e1aa8988e7aa",
        "friendlyId": 2,
        "keywords": ["bad", "idea", "bad", "idea"],
        "status": {
            "title": "On Track"
        },
        "phase": {
            "name": "Comment"
        },
        "fields": [
            {
                "kind": "LONG_TEXT",
                "title": "Description",
                "value": "This is a bad idea"
            },
            {
                "kind": "SHORT_TEXT",
                "title": "Title",
                "value": "Bad Idea"
            }
        ],
        "owner": {
            "firstName": "Test"
        }
    },
    {
        "id": "da011987-cfa9-49fa-b331-bb4ca0b2fa1b",
        "friendlyId": 1,
        "keywords": ["great", "idea", "great", "idea"],
        "status": {
            "title": "On Track"
        },
        "phase": {
            "name": "Comment"
        },
        "fields": [
            {
                "kind": "SHORT_TEXT",
                "title": "Title",
                "value": "Great Idea"
            },
            {
                "kind": "LONG_TEXT",
                "title": "Description",
                "value": "This is a great idea"
            }
        ],
        "owner": {
            "firstName": "Test"
        }
    }
]