Looking at the REST api for YouDontNeedACRM

I started looking at the REST API for youdontneedacrm - and I thought I'd share my experiences here in a blog post on DEV.

To start with you can get a 15 day free licence to use site (and the API) - so I started filling the code to create the account :

Now there is a part of the sign up that I found confusing - and it was around the type of account you want to set up - I don't have any screenshots of this section.

Once you have chose the account type that you would like to make, then eventually - you need to activate your account

one of the options to enable the account is to spread the word - hence this post on Linked In

Getting started with Insomnia

When I'm working with an API I like to document it using the Insomnia REST tool - it has the advantage of being both documentation and a testing environment - and you can download a partial Insomnia workspace that has the following functions set up

• Authentication
  • Login
  • Ping (API KEY)
  • Ping (User Token
  • GetUserToken (UserID)
  • GetUserTiken (User Email)
  • Logout
• Activities
  • Get Activities
  • Get Activities (User)
• Leads
  • Create a Lead
  • Create and Lead and assign to user
  • Create a Reminder

This is a very small subset of what the API can offer - but this is all the functionality I wanted to explore for the moment.

Authentication

The API docs say the following :

In order to secure your transaction, we ask you to use one of your generated api key or your user token with any https transaction.

In this version 2 of the API, you have the choice of making your requests:

• user not dependent using one of your API key: it is for the account and it grants you admin rights. Meaning if you create a lead for example with this api key without specifying a user, the lead won't belong to any specific user and will appear in the interface as an unassigned lead.
• user dependent using a USER token: all the requests will use the privacy of the users and some requests won't be allowed depending of the user rights.
• user not dependent using one of your API key: it is for the account and it grants you admin rights. Meaning if you create a lead for example with this api key without specifying a user, the lead won't belong to any specific user and will appear in the interface as an unassigned lead. user dependent using a USER token: all the requests will use the privacy of the users and some requests won;t be allowed depending of the user rights.

Impersonation

So the way the security model is set up is that you can use basic authentication to log in as a specific user. Logging in will return a user token (it isn't known how long the user token exists for - but there is a specific call to invalidate - or logout. You can now pass in the user token into all subsequent calls, and have every privilage that the user has.

I think this is a little worrying, and not a stategy I would suggest to follow. If a user leaves the group, or changes their password then scripts that have previously logged in as that user will no longer work.

Instead I would suggest using the API key approach - something that YDNAC supports, and is (in my mind) a better approach.

API Key.

The API approach, allows a script using the API to identify using a key that can be activated, deactivated and even removed through the administration dashboard. This doesn't tie the script to an individual user and is (in my mind) a more robust way of handling the authentication, and is more in line with what and how we'd expect to integrate with services - API Keys and tokens (as opposed to user credentials) seem to be the way that services like Twitter / Facebook / Github all handle authentication of systems that integrate with them.

To create an API token, navigate to (YOURSITE)/admin/api_keys and click the Create an API key button.

Broken bits

There are a few areas where I've found problems - primarily the Get activities endpoint always seems to return a 403 (forbidden) error - I'm not sure why - maybe I need to add some activities?

There are references to getting activity ID's within the API documentation - but nothing really about how to set up an activity - I'll investigate more, but I also can't find anything about activity while looking on the UI.

I also experienced a really strange error being returned from this REST API

Mike Hingley

@computa_mike

Hi @noCRM - I'm trying to call a rest API, and I get some very strange responses. I get a 200 but in the body I get this :

11:19 AM - 28 Aug 2020

but that was down to be POSTing something to a GET endpoint - even so - surely it shouldn't return a 200 status - more likely a 405 error?

Next Steps

For my experimentation I set up a quick .NET class to talk to YDNAC. I plan to take this class library further, and implement the full API.