5 ms·

Heroku Platform API, Now Available in Public Beta

60 points by Lightning 13y ago

swanson 13y ago
Can't wait for someone to build a "Deploy to Heroku" button that I can stick on a GitHub README. It will spin up the app, do all the setup and then pass it off to the end-user; the instructions for most Heroku deployable apps always follow the same repeatable actions so it would be awesome to automate this. I tried out this project with similar aims in the past: https://github.com/rainforestapp/heroku.json https://github.com/rainforestapp/heroku.json but it wasn't quite enough to get an app up and running.
- geemus 13y ago
  Those repetitive setup tasks are definitely one of the things we wanted to provide an easier solution for. I definitely look forward to simple scripts instead of multi-step manual processes.
- CGamesPlay 13y ago
  That sounds like a fun weekend project! Instead of "try a live demo" you get "create a live demo of your own".
  - geemus 13y ago
    Totally. I definitely hope that this will lead to many, many fun weekend projects. Definitely really excited to see what people dream up.
- igul222 13y ago
  How's this? git clone https://github.com/whatever; heroku create; git push heroku master
  - swanson 13y ago
    Well most apps needs some others like: heroku config:set SECRET_TOKEN=`openssl rand -hex 20` heroku run rake db:migrate heroku addons:add scheduler Open the scheduler webpage and add an hourly task heroku restart
    - geemus 13y ago
      Exactly. For simple cases just shelling out to the API is good enough, but many of these deployable apps are a bit more complicated. Especially those that need databases or other add-ons to work.
- Timothee 13y ago
  That's actually been one of my backburner projects for some time. But I haven't had much time recently… My approach though was having a Chrome extension to add that button on any GitHub repo. Clicking it would create the app, clone it and push it out to your own instance. Some things slowed me down though. For example the Heroku API doesn't play well with requests made with XMLHttpRequest inside the browser, so I wrote a simple proxy for that purpose. I started working on a Heroku app that would do the git cloning but haven't had much time on it.
  - geemus 13y ago
    Sounds like a great approach. What can we do to better support XMLHttpRequest?
    - Timothee 13y ago
      The problem I had with XMLHttpRequest was that the API would use the current Heroku cookie rather than the API token passed in with the request. With curl, the doc says to use a blank username and the token as password in Basic Auth. When I do that with XMLHttpRequest, the token is completely ignored and the main site's cookie is used. There is no way not to pass the cookie with XMLHttpRequest unfortunately, so I would have to rely on if the user is logged in or not. That would bring other problems: I could only use the API for one account at a time for example, and I would have to add checks to see if the user is logged in, etc. So my work-around was to write a proxy that would just pass around the requests to Heroku and the response back to the XMLHttpRequest client. (https://github.com/Timothee/Passeplat https://github.com/Timothee/Passeplat) With it, I can make the same requests I would make to https://api.heroku.com https://api.heroku.com but instead make them to mypasseplatinstance.heroku.com. Making this a Heroku-ready app is of course not a coincidence: my plan is to use my Heroku instances (the proxy and the yet-to-be-written git clone) to bootstrap a couple of Heroku instances with the user's own Heroku account. Then the extension would use these to start up other apps. I like the bootstrap idea: it's like compiling a compiler. :) I'm now realizing that it might even be done with a buildpack… I'd have to look into that. (that would remove the need for that second "git clone" app) Hum, I'll really have to look into that! That could make things much easier and cleaner. (and also cooler) There would still be the issue of specific configurations and add-ons to deal with, but that shouldn't be too hard if the rest is done. edit: I haven't checked if this is still a problem with today's announcement. Also, I contacted Heroku support about it, but they only suggested I use a proxy.
sync 13y ago
Didn't they already have this API available? Can someone explain how this differs from https://github.com/heroku/heroku.rb https://github.com/heroku/heroku.rb ?
- geemus 13y ago
  I would be happy to explain. We did provide a legacy API (v2), the platform API is the next iteration on the design (v3). The legacy API was mostly used just internally and we knew we could do better in providing a great public API for external folks to tie into and use for awesome stuff. Currently heroku.rb still uses the legacy API, as we did not want to introduce breaking changes to heroku.rb and because the legacy API will still be around for a while. We will build new tools and update existing ones, but plan to do so later in the beta so that we can integrate feedback and see what will best help people.
  - nthj 13y ago
    > The legacy API was mostly used just internally I find that amazing. I think every app I've ever worked on or built with Heroku has tied into the API in one way or another. It's one of your best features.
    - geemus 13y ago
      A number of people definitely found their way through the toolbelt code to use the API previously, which is amazing. We hope by giving a stronger focus and some proper documentation that we can make it much more accessible to more and more people.
mjackson 13y ago
High five for the Heroku API designer who decided to use the Accept header to indicate the acceptable format and version of the response. This is the way to design HTTP APIs. Instead, most companies put the version number in the URL and use special suffixes on the URL like ".json" to indicate these things. I can understand this practice from the standpoint of convenience. A human using cURL can't be bothered to type out an Accept header. But when building an API support should first be considered for explicit, programmatic API clients, not humans. Then you can slap on your human-friendly URL extensions, etc. It's always easier to start out being explicit.
- geemus 13y ago
  Thanks, glad you like it. A ton of thought went into a lot of the little choices like that. We plan to dig more into how and why those choices were made as we move forward.
  - edanm 13y ago
    This will be very interesting for those of us looking to learn more about building APIs. I for one am definitely looking forward to future posts on the subject!
    - geemus 13y ago
      Great, do let me know if there are particular questions you have and we can be sure to cover them. Otherwise I hope to start covering the key things that I think are interesting or important in the not too distant future.
- swaroop 13y ago
  +1. I did not appreciate these concepts until I watched Designing a Beautiful REST+JSON API http://youtu.be/5WXYw4J4QOU http://youtu.be/5WXYw4J4QOU
  - geemus 13y ago
    Thanks for sharing the link. There definitely can be a lot of gotchas and things that are easy to overlook until you see a good talk or are right in the middle of it.
superchink 13y ago
I can see this being a good candidate for a Vagrant provider!
- geemus 13y ago
  Yeah, that would definitely be an interesting way to use it.
benologist 13y ago
Does this mean you could build/sell addons that are full applications rather than external services?
- geemus 13y ago
  I had not really explicitly considered that possibility in working on this. I suppose this is a step closer to that, but there are still some pieces that we would need to add. What kind of things did you have in mind?
  - benologist 13y ago
    What I'm imagining is click a button and have it create and deploy fully configured apps for me, similar to what I can do with all the add on services. They might be paid or free or tiered etc, it might be a once-off fee or a monthly/annual subscription or an on-going charge like some of Amazon's AMIs. There's lots of commercially licensed, self-hosted software (blog, forum, ecommerce etc) and hosted-as-a-service (wordpress.com, discourse.org, duelapp.com etc) etc that would be applicable. Enabling that by API or in general would be awesome.
    - geemus 13y ago
      I was pretty sure that was the kind of thing you meant, but just wanted to clarify. The API should certainly facilitate doing the kind of setup and management that this would require. But it doesn't currently provide a direct way to do the billing portion of things. So I think it could be a ready solution to open source self-hosted stuff, for instance, but you would have to provide your own billing stuff for commercially licensed things.
      - aeden 13y ago
        Billing and provisioning. Please oh please let us provision new Heroku accounts. :-)
        13y ago
themgt 13y ago
From a glance this looks like a formalization of what already existed at: https://api-docs.heroku.com/ https://api-docs.heroku.com/ and which obviously the command-line client uses (although the docs and command line/production API have drifted apart) At Pogoapp we basically reverse-engineered our API from Heroku's command line client, but it's excellent to have Heroku make the API public and formal, because it should make that process much easier and set up Heroku's API as a good target for other PaaS hosts to standardize on (in the same way Ceph & RiakCS have S3-compatible REST APIs)
- geemus 13y ago
  We definitely used what you mentioned as a starting point. There are some changes, hopefully for the better, but it should in time provide all the same functionality in a more public and formal way. We definitely love that people were excited and motivated enough to reverse-engineer things as you did, so we hope this makes it easier on you and more accessible to others.

60 points by Lightning 13y ago

Can't wait for someone to build a "Deploy to Heroku" button that I can stick on a GitHub README. It will spin up the app, do all the setup and then pass it off to the end-user; the instructions for most Heroku deployable apps always follow the same repeatable actions so it would be awesome to automate this. I tried out this project with similar aims in the past: https://github.com/rainforestapp/heroku.json https://github.com/rainforestapp/heroku.json but it wasn't quite enough to get an app up and running.

geemus 13y ago
Those repetitive setup tasks are definitely one of the things we wanted to provide an easier solution for. I definitely look forward to simple scripts instead of multi-step manual processes.
CGamesPlay 13y ago
That sounds like a fun weekend project! Instead of "try a live demo" you get "create a live demo of your own".
- geemus 13y ago
  Totally. I definitely hope that this will lead to many, many fun weekend projects. Definitely really excited to see what people dream up.
igul222 13y ago
How's this? git clone https://github.com/whatever; heroku create; git push heroku master
- swanson 13y ago
  Well most apps needs some others like: heroku config:set SECRET_TOKEN=`openssl rand -hex 20` heroku run rake db:migrate heroku addons:add scheduler Open the scheduler webpage and add an hourly task heroku restart
  - geemus 13y ago
    Exactly. For simple cases just shelling out to the API is good enough, but many of these deployable apps are a bit more complicated. Especially those that need databases or other add-ons to work.
Timothee 13y ago
That's actually been one of my backburner projects for some time. But I haven't had much time recently… My approach though was having a Chrome extension to add that button on any GitHub repo. Clicking it would create the app, clone it and push it out to your own instance. Some things slowed me down though. For example the Heroku API doesn't play well with requests made with XMLHttpRequest inside the browser, so I wrote a simple proxy for that purpose. I started working on a Heroku app that would do the git cloning but haven't had much time on it.
- geemus 13y ago
  Sounds like a great approach. What can we do to better support XMLHttpRequest?
  - Timothee 13y ago
    The problem I had with XMLHttpRequest was that the API would use the current Heroku cookie rather than the API token passed in with the request. With curl, the doc says to use a blank username and the token as password in Basic Auth. When I do that with XMLHttpRequest, the token is completely ignored and the main site's cookie is used. There is no way not to pass the cookie with XMLHttpRequest unfortunately, so I would have to rely on if the user is logged in or not. That would bring other problems: I could only use the API for one account at a time for example, and I would have to add checks to see if the user is logged in, etc. So my work-around was to write a proxy that would just pass around the requests to Heroku and the response back to the XMLHttpRequest client. (https://github.com/Timothee/Passeplat https://github.com/Timothee/Passeplat) With it, I can make the same requests I would make to https://api.heroku.com https://api.heroku.com but instead make them to mypasseplatinstance.heroku.com. Making this a Heroku-ready app is of course not a coincidence: my plan is to use my Heroku instances (the proxy and the yet-to-be-written git clone) to bootstrap a couple of Heroku instances with the user's own Heroku account. Then the extension would use these to start up other apps. I like the bootstrap idea: it's like compiling a compiler. :) I'm now realizing that it might even be done with a buildpack… I'd have to look into that. (that would remove the need for that second "git clone" app) Hum, I'll really have to look into that! That could make things much easier and cleaner. (and also cooler) There would still be the issue of specific configurations and add-ons to deal with, but that shouldn't be too hard if the rest is done. edit: I haven't checked if this is still a problem with today's announcement. Also, I contacted Heroku support about it, but they only suggested I use a proxy.

sync 13y ago

Didn't they already have this API available? Can someone explain how this differs from https://github.com/heroku/heroku.rb https://github.com/heroku/heroku.rb ?

geemus 13y ago
I would be happy to explain. We did provide a legacy API (v2), the platform API is the next iteration on the design (v3). The legacy API was mostly used just internally and we knew we could do better in providing a great public API for external folks to tie into and use for awesome stuff. Currently heroku.rb still uses the legacy API, as we did not want to introduce breaking changes to heroku.rb and because the legacy API will still be around for a while. We will build new tools and update existing ones, but plan to do so later in the beta so that we can integrate feedback and see what will best help people.
- nthj 13y ago
  > The legacy API was mostly used just internally I find that amazing. I think every app I've ever worked on or built with Heroku has tied into the API in one way or another. It's one of your best features.
  - geemus 13y ago
    A number of people definitely found their way through the toolbelt code to use the API previously, which is amazing. We hope by giving a stronger focus and some proper documentation that we can make it much more accessible to more and more people.

mjackson 13y ago

High five for the Heroku API designer who decided to use the Accept header to indicate the acceptable format and version of the response. This is the way to design HTTP APIs. Instead, most companies put the version number in the URL and use special suffixes on the URL like ".json" to indicate these things. I can understand this practice from the standpoint of convenience. A human using cURL can't be bothered to type out an Accept header. But when building an API support should first be considered for explicit, programmatic API clients, not humans. Then you can slap on your human-friendly URL extensions, etc. It's always easier to start out being explicit.

geemus 13y ago
Thanks, glad you like it. A ton of thought went into a lot of the little choices like that. We plan to dig more into how and why those choices were made as we move forward.
- edanm 13y ago
  This will be very interesting for those of us looking to learn more about building APIs. I for one am definitely looking forward to future posts on the subject!
  - geemus 13y ago
    Great, do let me know if there are particular questions you have and we can be sure to cover them. Otherwise I hope to start covering the key things that I think are interesting or important in the not too distant future.
swaroop 13y ago
+1. I did not appreciate these concepts until I watched Designing a Beautiful REST+JSON API http://youtu.be/5WXYw4J4QOU http://youtu.be/5WXYw4J4QOU
- geemus 13y ago
  Thanks for sharing the link. There definitely can be a lot of gotchas and things that are easy to overlook until you see a good talk or are right in the middle of it.

superchink 13y ago

I can see this being a good candidate for a Vagrant provider!

geemus 13y ago
Yeah, that would definitely be an interesting way to use it.

benologist 13y ago

Does this mean you could build/sell addons that are full applications rather than external services?

geemus 13y ago
I had not really explicitly considered that possibility in working on this. I suppose this is a step closer to that, but there are still some pieces that we would need to add. What kind of things did you have in mind?
- benologist 13y ago
  What I'm imagining is click a button and have it create and deploy fully configured apps for me, similar to what I can do with all the add on services. They might be paid or free or tiered etc, it might be a once-off fee or a monthly/annual subscription or an on-going charge like some of Amazon's AMIs. There's lots of commercially licensed, self-hosted software (blog, forum, ecommerce etc) and hosted-as-a-service (wordpress.com, discourse.org, duelapp.com etc) etc that would be applicable. Enabling that by API or in general would be awesome.
  - geemus 13y ago
    I was pretty sure that was the kind of thing you meant, but just wanted to clarify. The API should certainly facilitate doing the kind of setup and management that this would require. But it doesn't currently provide a direct way to do the billing portion of things. So I think it could be a ready solution to open source self-hosted stuff, for instance, but you would have to provide your own billing stuff for commercially licensed things.
    - aeden 13y ago
      Billing and provisioning. Please oh please let us provision new Heroku accounts. :-)
      - 13y ago

themgt 13y ago

From a glance this looks like a formalization of what already existed at: https://api-docs.heroku.com/ https://api-docs.heroku.com/ and which obviously the command-line client uses (although the docs and command line/production API have drifted apart) At Pogoapp we basically reverse-engineered our API from Heroku's command line client, but it's excellent to have Heroku make the API public and formal, because it should make that process much easier and set up Heroku's API as a good target for other PaaS hosts to standardize on (in the same way Ceph & RiakCS have S3-compatible REST APIs)

geemus 13y ago
We definitely used what you mentioned as a starting point. There are some changes, hopefully for the better, but it should in time provide all the same functionality in a more public and formal way. We definitely love that people were excited and motivated enough to reverse-engineer things as you did, so we hope this makes it easier on you and more accessible to others.