Articles in this section

New REST OpenAPI for Developers

Vine-Tuki
  • Updated
Follow

Introduction

Welcome to the new REST API that we have introduced to help you manage contacts, companies, subscription lists, and tags in your Vine database. The Vine REST API is an interface that employs HTTP requests (GET, PUT, POST and DELETE) to interact with a Vine database.

Getting Started

The Vine Rest API is available to all Vine MA users.  Availability of certain advanced features, like AI operations, varies based on your Vine MA plan. Before using the Vine Rest API, authentication is required, as unauthenticated users cannot make requests.

The root-endpoint is located at https://vine.eu/api/rest/ma/v1/

Authentication

In the Vine Rest API, authentication begins with the LOGIN request, generating a bearer token for subsequent REST requests.

1. Initial Authentication Using LOGIN request

For authentication in the Vine REST API, use the LOGIN request with your Vine API key. A successful LOGIN request returns a token for future calls.

Copy

Login Request using Vine MA API Key

curl -X GET -H "x-api-key:A92330D0425211ECA7C5454B9025CC97-13B0B98D-618C0D00" https://vine.eu/api/rest/ma/v1/login

This will return a bearer token like:

"5a80da50-055f-11ee-936f-2fa22a85c2c5"

Include this token in your subsequent API request headers.

Note: It's highly recommended to use x-api-key for improved security and to ensure your code functions even if the password changes.

Copy

Login GET Request with Username and Password (Basic Authentication)

curl -X GET -u "demo@vine.eu:demo" https://vine.eu/api/rest/ma/v1/login
Copy

Login POST Request with Username and Password Passed as JSON

curl -X POST -H "Content-Type: application/json" -d '{"username":"demo@vine.eu","password":"demo"}' https://vine.eu/api/rest/ma/v1/login

2. Further Token-Based Authentication

After the Login request, use the bearer token in subsequent API request headers as follows:

Copy

API Request using Bearer Token

curl -X GET -H "Authorization: Bearer f4d04630-0565-11ee-936f-2fa22a85c2c5" https://vine.eu/api/rest/ma/v1/contacts

The token remains valid for 1 hour after the last usage.

Content Types

The Vine REST API service only accepts requests with the Content-Type header set to application/json for both POST and PUT requests. For most of the response data, the Vine REST service uses the application/json content type. However, for certain media-related requests, such as image generation, the content type image/jpeg is used. Client applications should handle these content types based on the returned Content-Type header. There is no requirement for the client to set the Accept header, as the Vine REST service will disregard it during request processing.

Documentation

For detailed information about endpoints, parameters, request/response formats, and authentication methods, please consult the Vine REST API documentation and its Open API specification.

Usage Samples

How to Generate Typescript Client

Copy

Generating typescript client

docker run --rm -v \"${PWD}:/local\" openapitools/openapi-generator-cli generate -i https://vine.eu/api/rest/ma/v1/api-docs.json -g typescript-fetch --additional-properties importFileExtension=.js  --additional-properties useSingleRequestParameter=false -o /local/openapi/client

 

How to Import Typescript Client

Copy

Importing typescript client

import { AuthenticationApi, Configuration, ContactApi, TagApi } from '../../client/index.js';

 

How to Use Typescript Client

Copy

Sample code (adding a tag for a person)


               let defaultBasePath = 'https://vine.eu/api/rest/ma/v1';
               let authenticationApi = new AuthenticationApi(new Configuration({ basePath: defaultBasePath, apiKey: Config.vineRestApiKey }));
               let bearerToken = await authenticationApi.login();
               let contactApi = new ContactApi(new Configuration({ basePath: defaultBasePath, accessToken: bearerToken }));
               let emailAddress = 'someemail@some.com';
               let contacts = await contactApi.listContacts(emailAddress, 0, 1);
               let contactID: number;
               
               if (contacts?.length == 0) {
                    contactID = await contactApi.createContact({ email: emailAddress, firstName: currentUser.firstName, lastName: currentUser.lastName, mobilePhoneNumber: currentUser.mobilePhoneNumber });
                } else {
                    contactID = contacts[0].id;
                }
               
               let tagApi = new TagApi(new Configuration({ basePath: defaultBasePath, accessToken: bearerToken }));
               let tags = await tagApi.listTags('SOME_TAG');
               let tagID: number;
               
               if (tags.length == 0) {
                    tagID = await tagApi.createTag({ name: 'SOME_TAG' });
                } else {
                    tagID = tags[0].id;
                }
               let tagResult = await contactApi.addTag(contactID, tagID);

Related articles

Comments

0 comments

Please sign in to leave a comment.