Upcoming API - Calling all Developers
As you may already know from other posts circulating Snapzu that we are scheduling to build an API that we plan to release some time in the next 2-3 months. We have thought about it long and hard and realized that at 2-3 month release date isn't good enough. So, we need your help! Our idea is to list the general things we would like and not like for a first version API to have and then continue working on it to release additional functionality as we grow and mature as a platform.
Functionality we don't wish to release with initial release
- Ability to create / manage / edit snaps
- Profile settings / visual settings
- Tribe Management / settings / visual settings
Functionality we would like for initial release
- Account creation
- Account login / management
- Access to snap / text post / comment history
- Ability to vote on all comments / snaps / text posts
- Ability to comment on snaps / text posts
- Ability to create text posts
- Ability to private message
- Profile Overview
If we can create a barebones API we would be able to release it much sooner (possibly inside 1.5 months). This will also allow us to continue working with developers on upcoming features which can be added to later releases. As a developer please let us know what type of barebones features you would like to see in the initial release (maybe we forgot some very important functions). We are also looking for general feedback on everything to do with API's. We plan to start next week, so any discussion on the subject is important to us, as we would like to work with you on making this the best API possible.
Join the Discussion
I think it might be worth the time and effort to check out Reddit's own API. You can probably come up with a list of core function ideas pretty quickly. You're doing a lot of the same stuff.
Would probably recommend separate milestones for the api. milestone 1 will get a user logged in, read sort and post snaps. aim for 80% of site usability. Low hanging fruit. I think for milestone 1, the list will look like:
* user auth
* Ability to vote on all comments / snaps / text posts
* Ability to comment on snaps / text posts
* Ability to create text posts
milestone 2 will get profile editing and tribe management, searching, etc, milestone 3 will get more goodies (the rest of the 20%).
Document, document, document. Use something like Swagger to hold the docs. It's lovely.
REST not SOAP. JSON not XML
Sorry. sort of a brain dump. hope some of that's useful to ye.
[This comment was removed]
[This comment was removed]
+1 to this swagger. There are several tools built around it.
Just to add to this do proper REST. This is not proper REST, think resources/nouns not verbs, if you think your resources right the API will be easier to future proof. Consider using HATEOAS (with JSON) because it may make well implemented clients more resilient to changes.
I think that gets a big, fat "duh!" these days.
Personally I would love to see your team introduce even more iterations so app creators can get working and users can get some value. With a quicker release cycle app devs can get to work now on UI and basic items. Then iterate with you as new API features are released.
Phase 1 - Lurker
- Account login (no management.)
- Access to view snaps
- Ability to vote on snaps
Phase 2 - Commentator
- Ability to comment on snaps / test posts
- Ability to vote on comments / snaps / test posts
Phase 3 - Content Creator 1
- Ability to create text posts
Phase 3 - Snapzu Power User
- Ability to private message
- Profile Overview
- Tribe Management
I think you're on to something, definitely more phases / iterations would be beneficial in speeding up the creation of the API so that devs can get started with the basics and then adding functionality as we fine tune and release updated versions. Anyone else agree with this? or not agree for that matter?
I'm not a developer, but I really like the phases setup like this. I think the first priority should definitely be to get something in place that'll allow users to login and read posts from tribes they are subscribed to. I'm okay with this phase layout, but I think the optimal first phase would be a combo of 1 and 2.
Taking into account that phase 1 should enable the creation of a decent mobile viewer, I'd add one thing : requesting an authentication nonce. That way the app could link the user to the right web page ready to comment or do whatever, pre-authenticated.
Yes, I think short iterations so that devs who want to use the API can get started sooner is the way to go.
I agree with this. Although I would personally prefer the original post way of doing it, but this could be a good start.
This comment has been removed
I think /u/jrmy's list is a good one, with one caveat: I think creating text posts should be part of the same phase as creating snaps. From a (non-programmer) user's perspective it would be weird and frustrating if I could post text posts but not snaps.
The only reason I left out posting snaps was due to my perceived level of effort needed to support a snap vs a text post. With snaps having modules, etc, I could foresee that being an issue. But, now that I think about it, there is no reason you couldn't provide a limited snap posting release that doesn't include most of the modules.
Yeah, I agree with that.
Facebook did it with their Platform and it seems like it's what made the whole thing work.
I think this makes sense, although I'd add the ability to create snaps somewhere in there (possibly just an oversight). Also, I'd give tribe management it's own later phase as I don't think it should hold up 'profile overview' and PMs. It's a social community after all.
I think as long as phase 1 includes the ability to get a list of subscribed tribes, then I think that's pretty much the way to go.
From a developer perspective, this is probably the best (most practical and logical) list that I've seen here.
This. This this this. That would be a great way to accelerate the development, and would allow us to put out stuff faster. Phase 1 and phase 2 could go together though, as it would be pretty badly received (IMO) to not be able to comment, as it's pretty much what's encouraged in this community!
Yeah, I like this list. From a developer's perspective, the only thing that makes things hard is when breaking changes are made to existing APIs. As long as that's avoided as much as possible, releasing the API in phases like this should work pretty well.
Great Idea!
I think as a 'barebones' list, you have a pretty good list there. Though I do think the ability to add/edit snaps will need to come soon, especially as some users have said that mobile devices are their primary interaction with the site.
Agreed. That'd be the one big missing feature.
However, having basic reading/commenting functionality ASAP is a must. The only reason I am spending more time on reddit than snapzu at the moment is because I am mainly on mobile.
I agree. I definitely use the site more on mobile
Do realize that as soon as the API is released all of the mobile devs then have to build apps. I think that that should be one of the next features, but I think this list will make developing the app easy. And then adding the posting should be simpler.
Also I know that I could easily hack together a way to post data to the site without an api. However processing the page to try and pull snaps out of the website would be considerably harder.
I worked as a developer at a company whose main product was an API, so I definitely have some thoughts. Your list of features seems reasonable to me, but in my opinion the most important questions are more subtle.
There's a crucial step that's easy to overlook: Make sure you have a solid plan for how you're going to update your API. The ideal is a versioned API, where old versions are supported indefinitely. If that's not plausible for you, consider how you're going to communicate changes to developers with enough lead time for them to update their apps. (And you'll still want to version things, because it's no good to make everyone deploy at the exact same time as you.) Remember that since you don't have control over third-party code, even changes that seem totally innocuous to you might break things.
It's often hard for a web company that's used to agile-style fast release cycles to get in the proper mindset for maintaining an API. The ideal is for breaking changes to be rare, and done with a lot of lead time. This can of course be different in a beta period, but communicate that heavily and plan to lock things in eventually.
Related to the above, try to give good error messages when things go wrong. There's a big difference between "our servers are having trouble right now" and "the route you're using doesn't work any more". Developers won't have access to your server logs, so they'll be relying on you for debugging information.
Thinking about the business side of things is also important. Start thinking now about what sort of apps you'd be tempted to try to shut down, and whether you're going to do that. Try to come up with a terms of service that you can live with for a long time, because nothing makes developers more wary of a company than them shutting down any third party service that gets too popular.
Get all of that right, and you'll be head and shoulders above 90% of APIs out there. :)
I worked at one where the product was available 100% through an API and where our own interface used only the public API.
The most overlooked piece of advice I can give is : look out for typos, you're going to look silly for a very long time otherwise!
Also, your API stability (alpha, beta, stable) may be per path so you can advise users of what is just a test and have their feedback.
Definitely a good call about the typos!
Couldn't agree more, we plan to keep meticulous documentation, version control and a moving forward only approach with new API versions. We realize that changing even the most trivial functionality in the API can cause issues.
Yes, we do plan on having a beta period dedicated to working out the kinks.
Some great advice here, thank you.
This is all great. I've worked with the API's on the product I work on at my job (for automating repetitive tasks) and having useful errors is one of the biggest problems I ran into when trying to accomplish a certain task. Having a versioned API is also a must or API users will be scrambling to find out when a new version is released.
I would definitely be interested in helping!
Don't forget your bot policies, an API means people will try to automate their accounts.
I give my ideas about that here.
But for your barebone release, you should probably disallow them for the time being.
It does sound logical to disallow them at first, at least until we figure things out.
This is really important i can't state this enough, people need to pay attention to your post, because a bot to run a tribe is ok, but bots ruining tribes can be hell.
Talking about bots to run tribes (moderate tribes) is it possible to do that here, does anyone know?
There's no API yet so there's no bot yet.
I think that bots can be very good but like downvotes, they should be limited so they can't be abused to cause massive damage.
yes i know there is no API therefor no bots, but that will most likely be possible using the bot to do the good things and moderate your tribe if needed right?
First question is : Are they users? In the bot topic I started I suggest they shouldn't be, they should be marked as bots. It's an important question here because if they are users they occupy a mod slot.
For instance, let say I make a scheduled post bot reponsible for posting a discussion at a regular interval and making it sticky and /u/double2 makes one that bans everyone that uses any other noun than snappers to refer to snapzu users. If you use both, it costs you two mod slots. It makes only swiss knife bots viable.
Second is how much info and access do you want to give my bot and therefore me by proxy? On reddit the all purpose mod bot was automoderator, you gave it full access and it didn't matter because its creator was a reddit admin to begin with so he had access to everything anyway. The permission system for bot mod assistants would require some thoughts.
Team Snapper would never implement such draconian laws. Why ban a dissident when you can just gang up on them and attempt to convert them via peer pressure?
But in all seriousness, it'd be nice if Snapzu are considering the way bots will interact with the site's framework from the beginning that they could create specially earmarked bot accounts with special allowances. Or perhaps bots could operate on an entirely parallel level, where instead of adding bots as mods, you have a bot-list which is just /u/[botname] in a series of input boxes, which would then permit whatever mod level duties you select from that bot on that nominated tribe?
This kind of talk really gets me excited. I hope this site becomes as good as all these suggestions and positive feedback makes me anticipate it will.
I'd go with /b/[botname], it might not be progressive but I believe in bot segregation.
That wouldn't be a bad idea. That would even allow for specially formatted bot profiles which show the bots owner details and statistics about what it's been doing.
We think alike.
This comment has been removed
Would you like this stickied, Drunkenninja? That way it won't get buried in the pile.
Sounds good.
What will the developer signup look like? Forgive me if that's already in place, I didn't see anything about.
We don't have one yet. But we will shortly.
Are you dogfooding this API internally? Tacking an API onto an existing site makes maintenance harder and leads to diverging features. Using the same API as your users generally leads to a nice API.
This is the ultimate test of usability. You need to make this API the tool you use for ALL of your interactions with the underlying server architecture. If you have a special set of tools whose utility outstrips that of your public-facing API, then you'll always have to replicate that work for the public sooner or later, and now you're supporting two APIs instead of one.
This is something we will be discussing at length during our next meeting. Thanks for pointing this out.
Honestly, that is one thing that has to be seriously considered. I don't care for a longer development time frame, most people can wait. We can be spoonfed, to a certain extent. I think it would be better, for devs and for users, to get some good APIs, stable and well implemented, than getting some half-assed API that breaks all the time and is hard to fix.
More work for you in the first place, but it will make our life and yours easier in the medium-to-long-run!
Ain't no thing. It's one of those things that's a lot of initial work but has the most long term benefit. If you like your API, then so will your users. It'll also help create "snapzu the platform" vs "snapzu the website". That and it's a pet peeve of mine when it's clear a site's API was developed independent of the site. ;)
I'd kill for a Windows 10 app, just putting that out there. I think the aesthetics of the site would go very well with it.
I'm a developer who intend to upgrade to Windows 10 and play around with Visual Studio 2015 Community Edition as soon as both of these are released. VS 2015 will support the latest Windows 10 API's. I like this website and it would be fun to at least play around and see. Visual Studio will be free for development on the conditions that it's being used for open source projects, which I guess this one could very well be since it would in that case just be a spare time project.
Eeeeeeeeeeeeeeeeeee! Please!
Do you mean the ability to check notifications? Because I feel like this is pretty hugely required. If that's not what you mean, I would definitely add it to the list! :)
I miss the orangered
Ability to see your notifications would be good for an initial release, I feel. I also think that create/manage/edit snaps should come, if not barebones, at least very soon after barebones, as this is pretty key.
I'd also like to ask for some more technical details (security - presumably you're going to go down access tokens route, how will that work for sign-in, users, how long will tokens be valid for, app identification, etc?, return types, i'm guessing json at first and maybe xml later, or just json?), if that's cool?
A user based notifications dump should be simple enough to implement into the initial API release. We will definitely consider this being a part of the first release.
[This comment was removed]
As others have already said, a REST API would be the proper way to go. Not only is it "pure" enough to allow the API to evolve over time, you can find libraries to consume REST APIs on every platform (desktops and mobile devices)
I would also suggest a more "Agile" approach: rather than "initial release" v. "the rest" I think you should try to release early, a very focused set of features, and have sprints to allow you and us to sync. on the best direction for the API. If that's OK, obviously :)
Speaking of API I am working on what I would call a concept for a mobile application on Android, if anyone would like to give feedback and suggestions feel free to join /t/snapzit
Here is a picture of how it looks right now
Your screenshot is not loading, looks like a broken link.
Imgur had a downtime when I was trying to upload so I had to find any alternative.
There.
Don't forget /u/ and /t/ mentions (your own username and /t/ for any tribes you are chief of, or maybe moderator).
Is this in regards to notifications? Would you mind clarifying?
Yeah, but more have a specific call where you can pull back mentions as a feed. There can be a notification feed where it shows replies and so on... actually think of it like this:
- api.snapzu.com/self/notifications/ - Lists all notifications for self.
- api.snapzu.com/self/notifications/replies/ - Lists just replies to comments
- api.snapzu.com/self/notifications/follows/ - Shows who has followed you
- api.snapzu.com/self/notifications/mentions/ - Shows conversations where your name has been mentioned.
- api.snapzu.com/tribes/notifications/ - List all notifications for tribes you are chief of or moderate
- api.snapzu.com/tribes/notifications/downvotes/ - List any snaps / comments downvotes in tribes you moderate.
- api.snapzu.com/tribes/notifications/mentions/ - Shows List of who has mentioned your tribe.
etc