With Numerly, the default channel when creating a number is called “Create Your Own.” The value for these types of numbers are only changed when you manually change them. You might use this to keep track of your child’s allowance, or maybe to keep a tally of calories you’ve consumed today.

You can also update these types of numbers with the API. There are three endpoints you can call to set, increment, or decrement a number. Each of these endpoints occur over secure HTTPS as a POST request using your APIKEY and refid.

The URL used in these examples might not be the final URL when the app is launched. I’m currently using Heroku as a SaaS provider and I don’t plan to change; however, the URL might change to be something a bit more official.

Authorization

Each API call requires an HTTP header named APIKEY whose value is provided from the app. The APIKEY is used to verify that the number you’re changing is owned by you. You’ll want to keep this secret.

The refid

Every number has it’s own reference identifier (refid for short). The refid is unique to each number, and it is used by the API to determine which number to set, increment, or decrement.

Setting a number

You can set a number to particular value using the example below.

 curl -i -X POST -H "Content-Type:application/json" -H "APIKEY:{insert your apikey here}" -d '{ "number": { "refid": "{insert your refid here}", "value": "68" } }' https://numerly-api.herokuapp.com/number/set 

If everything works correctly, then you’ll receive a response like this.

{"data":{"success":true}}

If an error occurs, then you’ll get very detailed information about what happened.

{"errors":["value element missing."]}

Incrementing a number

If you only need to bump a number by a certain value, then you’ll want to use the increment endpoint. The value can be positive or negative. Positive numbers will bump the value up and negative will bump it down. Note that the body of the request didn’t change and you only need to change the URL. The response will be the exact same too!

 curl -i -X POST -H "Content-Type:application/json" -H "APIKEY:{insert your apikey here}" -d '{ "number": { "refid": "{insert your refid here}", "value": "0.5" } }' https://numerly-api.herokuapp.com/number/inc

Decrementing a number

You can use the increment endpoint to decrement a value if you pass a negative number. You can also call the decrement endpoint with a positive number to do the same. Again, the body and the response is the exact same.

 curl -i -X POST -H "Content-Type:application/json" -H "APIKEY:{insert your apikey here}" -d '{ "number": { "refid": "{insert your refid here}", "value": "1.2" } }' https://numerly-api.herokuapp.com/number/dec

Summary

You can extend many of your own numbers by using the API. The uses are endless and I hope you enjoy integrating your projects into Numerly. I truly believe it will be a fantastic platform to showcase your numbers!

Advertisements

4 thoughts on “API

  1. If you’re planning the API does that mean that the app is quite far along the development path? How would a user interact with the API (via a service like IFTTT perhaps)?

    Like

    1. I wouldn’t say that the app is quite far along; however, I’m really making good progress. I’m laying the foundation now so that (hopefully) future progress goes smoothly. I’d like to make adding new channels to the app as easy as possible. I’m also keeping an eye on operating costs which is tough. Some challenges might be easy to overcome with unlimited funds, but are much more challenging when trying to stay lean.

      Right now, the dashboard and new-number screens are pretty solid. I think the API is too. I’m moving on to working on the view, edit, and delete pieces of functionality next.

      There are also three channels that are working pretty well. They are the Create Your Own, Countdown, and Google Sheets channels. I’m debating on how many channels are needed for a release. Any suggestions?

      Next Monday, I’ll do a blog post about IFTTT integration! Sounds fun!

      Like

      1. Cool. Wouldn’t know about how many channels for a convincing start. You’ve certainly got a good baseline there. If you could start with IFTTT support you’d introduce a great deal of flexibility to users that they would appreciate. Also it could be quite a bit less work on your end for the amount of options you provide: one channel for you to make work; many options for users.
        But I understand that IFTTT’s business model is to charge their channels a fee and that has scared away some smaller developers (such as Launch Center Pro recently). So that is a risky move.

        Like

  2. Reblogged this on The Occasional Tech Blog and commented:
    Looking forward to seeing how this app, Numerly, turns out. Hoping it will be a great successor to ill-fated Numerous. Will be a pity to no longer rely on my custom number dashboards in Google Sheets (something I really should have written a blog about a long time ago).

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s