Shop Mobile More Submit  Join Login

API Updates

Tue May 6, 2014, 2:47 AM
We are pleased to announce the release of a new API backend framework and documentation to support future growth of the deviantART & Sta.sh API's.

New Docs2 by muteor

Endpoint2 by muteor



Whats Changed?


We have been busy over the past few months creating a new framework that will allow us to make changes to the API faster.

The main new features are:
  • Versioning - We now support versioning of endpoints meaning we can make backwards incompatible changes.
  • Error Responses - We have standardized our error responses to make it easier for you to handle errors.
  • Request Specifications - We now have fine grained endpoint parameter specifications that improve request validation greatly.
  • Response Specifications - Responses are now predefined so your client will always receive consistent responses and types from the API.
  • Automated Documentation - All of the above means we can auto-generate documentation so that it doesn't become out of sync when we make changes.

Versioning


The ability to version changes to the API is one of the more important new features as it means we can now make backward incompatible changes without breaking older client implementations.

Major versions are specified via the URI of the endpoint and the current major version is v1, for example the whoami call is now: 
/api/v1/oauth2/user/whoami
Minor versions are date based E.g. 20140101 and are requested via the special request header dA-minor-version. If you do not send the header your client will always receive the latest minor version available.

Note: You do NOT need to update your current clients, all requests that do not contain the /v1/ major version in the URI are locked to v1.0 automatically.

Check out the full versioning documentation.

Errors


One of the more inconsistent parts of the old API was its error messages, we have now simplified the error codes and returns to make it easier for your clients to handle error states.

Old style errors are still returned if the request does NOT contain /v1/ in the URI. These will be documented with the endpoint and are marked as deprecated. 

Check out the full errors documentation.

The Future


The point of all this work is to make it possible to release new endpoints in the future. So far we are carefully testing the framework and considering what new endpoints can be released. We don't take the decision to release a new endpoint lightly - it is something that must be well designed, coherent and easy to use and something that we must support for a long time to come.

If you have a burning desire for a particular endpoint that would allow you to do something awesome, then we'd love to hear your thoughts. Please bear in mind that we will only be releasing new endpoints once we are confident that they will work well, be useful to a wide audience and be something we can support log term.

 


Add a Comment:
 
:iconfinwe:
finwe Featured By Owner Edited Oct 16, 2014
Is there any chance to add an endpoint for getting deviations list of the authenticated user in a close future? And folders lists... And deviations in a specific folder...
Right now, I am using the old school DiFi. And to use DiFi properly, i have to find user-id (the system id number) first.. To do so, i have to make a standard HTTP request from user's profile page. So, unnecessary data traffic. And even more, a DiFi gallery response is a lot of data, because of the HTML strings. Another unnecessary data traffic...
So, if you can add some endpoints for deviantArt Gallery it could be awesome..

For example:
GET   /gallery/deviations?[count, offset, order(latest, popular)]
GET   /gallery/folders?[count, offset]
GET   /gallery/folder?[count, offset, order(latest, popular)]

---
Reply
:iconmuteor:
muteor Featured By Owner Oct 18, 2014  Hobbyist General Artist
We have more endpoints coming soon, so you wont need to use DiFi for much longer.
Reply
:iconzeruch:
zeruch Featured By Owner May 19, 2014  Professional General Artist
API versioning = very smart.
Reply
:iconquanno3:
Quanno3 Featured By Owner May 11, 2014  Hobbyist Digital Artist
Are there any plans to implement statistics like the views, favourites and downloads into the API? Right now I have a (horrible) workaround by getting them from the DOM, so I first need to fetch the whole page. It'd be much more efficient if they could be added to the standard oEmbed call.
Reply
:iconrosscomt:
RosscoMT Featured By Owner May 10, 2014  Professional General Artist
I will get started on a more official iOS app later this year which supports a lot more functionality.
Reply
:iconlablayers:
LabLayers Featured By Owner May 9, 2014  Student Interface Designer
Reply
:iconrestrainedraptor:
RestrainedRaptor Featured By Owner May 9, 2014   Digital Artist
I noticed that most of these endpoints break the standards for HTTP verbs. Things like renaming and moving stash folders should be POST-only, not GET, and deleting a submission should obviously be a DELETE verb.
Reply
:iconmuteor:
muteor Featured By Owner May 10, 2014  Hobbyist General Artist
Yeah those POST and GET ones are there for backward compatibility because the old system allowed both, also the API is not a REST api just plain http. Not sure what the original reason was to not be restful but we are stuck with it now :)
Reply
:iconmuteor:
muteor Featured By Owner May 10, 2014  Hobbyist General Artist
All the input/output is automatically escaped so no chance of XSS via the api.
Reply
:iconrestrainedraptor:
RestrainedRaptor Featured By Owner May 10, 2014   Digital Artist
I figured that it'll be difficult to change now. I just hope nobody gets trolled with some nasty XSS.
Reply
:iconphotofroggy:
photofroggy Featured By Owner May 9, 2014  Hobbyist Artist
Actually renaming and moving items could do with being UPDATE, if you're going with a RESTful API.
Reply
:iconrestrainedraptor:
RestrainedRaptor Featured By Owner May 9, 2014   Digital Artist
Yup! I wasn't trying to be too specific but yeah, everything like that... Just as long as it's not GET. :)
Reply
:iconphotofroggy:
photofroggy Featured By Owner May 9, 2014  Hobbyist Artist
There's not really much need to use DELETE if it's not a RESTful API, though.
Reply
:iconrestrainedraptor:
RestrainedRaptor Featured By Owner May 10, 2014   Digital Artist
Mhm... Still, better to use POST than GET for anything that makes changes, because of XSS and all that.
Reply
:iconphotofroggy:
photofroggy Featured By Owner May 9, 2014  Hobbyist Artist
With the whole error values and stuff, I think it would be a lot cleaner to just have every response contain a `status` field, with 0 = success. I really don't like this business of using strings for status codes. They're codes. Not descriptions.
Reply
:iconphotofroggy:
photofroggy Featured By Owner May 9, 2014  Hobbyist Artist
Yay updates! :dummy:

Why is there a need for a hash at the end of documentation URLs?

A note about this page: www.deviantart.com/developers/…

Granted I don't know much about how file uploads work with CURL and other apps, but the example shows `test=@filepath`. The documentation does not mention a specific parameter for the file being uploaded, and does not mention a parameter `test`.

If I ever bother looking into how to do this sort of this then mentioning this will probably seem pretty stupid in hindsight. But whatever.

Great to see that you're actually using numbers for error codes now, rather than strings! That said, this still seems a little inconsistent.

If the error is not specific to an endpoint, the API still returns a string error and no appropriate error code? This is not too helpful. Sure, HTTP header codes can be used, but this is not too helpful on its own. Unless we are to assume endpoint-specific errors always have an HTTP status of 402, which seems reasonable.

Typo on the errors page:

"If you receive a 500 error it is reasonable for your client to retry that request for a maximum of three retires."

I think /user/whois would be nice for providing a way to perform user lookup. Accept a username and/or user ID of some sort. I don't think such an endpoint should necessarily require authentication. Depends on the amount of information returned. Providing this method would allow apps/websites to check if someone has changed their username, maybe. But I guess in most relevant cases there, there would be sta.sh keys associated with the user.

Message Centre APIs are an absolute must but I'm not going to harp on about it.

APIs for interacting with other parts of the site would be nice. Retrieving comments associated with a deviation/comment and submitting comments may go down well. Maybe put a cap on comments/(second||minute||hour).

APIs for notes, but this falls into MC stuff.

APIs for managing your watchlist/friends, but, again, this may fall into MC stuff.

Ok, so, maybe rather than a /user/whois method, how about an API method to return profile information for a given user. This could be used to construct some sort of view in an application briefly representing another user. And then if there were APIs for managing watches, a button could be provided by the app allowing you to add the guy to your watch list. Or remove them. Whichever. As such, may be helpful to indicate in a response to a profile request whether or not you are watching the user.

Retrieving a user's gallery via the API, so apps don't have to rely on RSS. Keep this separate from any API returning profile information. Or maybe provide the information in the same request, but as an optional thing. I think there should definitely be two standalone endpoints in any case.

There's a lot on dA that could do with an API, really.
Reply
:iconmuteor:
muteor Featured By Owner May 10, 2014  Hobbyist General Artist
Why is there a need for a hash at the end of documentation URLs?

The hash in the url is just an internal way of finding the correct endpoint to render the docs from.

Granted I don't know much about how file uploads work with CURL and other apps, but the example shows `test=@filepath`. The documentation does not mention a specific parameter for the file being uploaded, and does not mention a parameter `test`.
The `@` is just part of curl @ tells curl its a file and the `test` field is used because for stash uploads we dont check the field name we just process any files sent.

If the error is not specific to an endpoint, the API still returns a string error and no appropriate error code? This is not too helpful. Sure, HTTP header codes can be used, but this is not too helpful on its own. Unless we are to assume endpoint-specific errors always have an HTTP status of 402, which seems reasonable.
I think this actually makes things much simpler, first you branch on http status (detect non 200) and then if needed you can branch on the error or the error_code and user errors will be in error_details. We decided against having a status field because its a waste to include it in every response, where you can either check that you have the correct data or just check the http status.

I think /user/whois would be nice for providing a way to perform user lookup. Accept a username and/or user ID of some sort. I don't think such an endpoint should necessarily require authentication. Depends on the amount of information returned. Providing this method would allow apps/websites to check if someone has changed their username, maybe. But I guess in most relevant cases there, there would be sta.sh keys associated with the user.
Message Centre APIs are an absolute must but I'm not going to harp on about it.
APIs for interacting with other parts of the site would be nice. Retrieving comments associated with a deviation/comment and submitting comments may go down well. Maybe put a cap on comments/(second||minute||hour).
APIs for notes, but this falls into MC stuff.
APIs for managing your watchlist/friends, but, again, this may fall into MC stuff.
Ok, so, maybe rather than a /user/whois method, how about an API method to return profile information for a given user. This could be used to construct some sort of view in an application briefly representing another user. And then if there were APIs for managing watches, a button could be provided by the app allowing you to add the guy to your watch list. Or remove them. Whichever. As such, may be helpful to indicate in a response to a profile request whether or not you are watching the user.
Retrieving a user's gallery via the API, so apps don't have to rely on RSS. Keep this separate from any API returning profile information. Or maybe provide the information in the same request, but as an optional thing. I think there should definitely be two standalone endpoints in any case.
We will be certainly looking at most/all of these in the future.
Reply
:iconphotofroggy:
photofroggy Featured By Owner May 10, 2014  Hobbyist Artist
"The hash in the url is just an internal way of finding the correct endpoint to render the docs from."

Seems like an implementation detail that should be hidden. It just looks like extra crud and makes it impossible to remember links off-hand without memorising every endpoint's hash. Surely there must be another way to resolve the endpoint?

Regarding the specific documentation pages, I think it would make more sense to not have the different sections (parameters, response, etc.) collapsed by default. Not sure if they need to be collapsable at all. Those details are the main reason people even visit those pages. probably shouldn't be obscured by default.

Would it be possible to get some sort of roadmap for API features, even if it's vague?
Reply
:iconmuteor:
muteor Featured By Owner May 10, 2014  Hobbyist General Artist
No roadmap, I can say its going to be a while before we release any new endpoints.
Reply
:iconthefusa:
thefusa Featured By Owner May 9, 2014
What types of apps or sites do you expect to use the API?
Reply
:iconaimanstudio:
AimanStudio Featured By Owner May 9, 2014  Professional Digital Artist
Cool :D
Reply
:iconyukuii:
Yukuii Featured By Owner May 9, 2014   Digital Artist
Another idea .
When you block an annoying user, this person can not see my gallery and coments

Reply
:iconbaronbeandip:
baronbeandip Featured By Owner May 9, 2014
Unrelated to the dA API.
Reply
:iconyukuii:
Yukuii Featured By Owner May 9, 2014   Digital Artist
I think it's a good idea Bucktooth 
Reply
:icone1fking:
E1fking Featured By Owner May 8, 2014  Hobbyist General Artist
you guys should change the layout
Reply
:icontimberclipse:
TimberClipse Featured By Owner May 8, 2014  Professional Filmographer
Awesome! 
Reply
:iconlogeg:
logeg Featured By Owner May 8, 2014  Hobbyist General Artist
Message Center related endpoints, even read-only. What is now done by third-party notifiers via crude DiFi..
Reply
:iconarturoilhuitemoc:
ArturoIlhuitemoc Featured By Owner May 9, 2014
I second you. I can't do anything without a Message Center API.
Reply
:iconbaronbeandip:
baronbeandip Featured By Owner May 8, 2014
:iconbraceyourselfplz::iconsaysplz:Brace yourself, for the smell of incoming APIs are in the air.  (Or so it would seem)
Reply
:iconlogeg:
logeg Featured By Owner May 9, 2014  Hobbyist General Artist
Nah, last time I spoke with dA devs they said that the messaging system needs a major overhaul first.
Reply
:iconda-hobo:
dA-Hobo Featured By Owner May 6, 2014  Hobbyist General Artist
Awesome! This should help keep things running smoothly. 

Great job!
Reply
:icondeathshadow--666:
DeathShadow--666 Featured By Owner May 6, 2014
why doesn't the error documentation list all the possible errors?
Reply
:iconmuteor:
muteor Featured By Owner May 6, 2014  Hobbyist General Artist
It does, they are grouped so you don't need to know the exact error. Basically anything that is not 200 should be handled as an error, from there you can choose how granular you want to go. So after https status there is the error field which can be one of four values and after that there is error_code which only some endpoints use and will be listed the endpoints Errors section like here www.deviantart.com/developers/…
Reply
:iconbaronbeandip:
baronbeandip Featured By Owner May 6, 2014
For clarification: www.deviantart.com/oauth2/toke… does not have a major version?
Reply
:iconmuteor:
muteor Featured By Owner May 6, 2014  Hobbyist General Artist
Doesn't actually matter for oauth endpoints because the spec is 2.0 final now anyway. But it will work with or without the major version, I should probably update that.
Reply
:iconbaronbeandip:
baronbeandip Featured By Owner May 6, 2014
Great job gentlemen (and ladies if there are in #dT).  #dT delivers.
Reply
:iconbaronbeandip:
baronbeandip Featured By Owner May 6, 2014
any*
Reply
:icondahub:
dAhub Featured By Owner May 6, 2014
If you have a burning desire for a particular endpoint that would allow you to do something awesome, then we'd love to hear your thoughts
I wish whois listed the user's time zone so we could display timestamps correctly

It would be nice if the response types indicated the max bytes required to store the data, such as 30 characters for username or 16 bytes for UUID once the dashes are stripped.

It would be great if we could disable certain sections of the API that we don't need.  I talked with a Community Volunteer who did not want to use an application because the Authorization page requested access to her Stash, even though the app itself never used the Stash.  Some checkboxes in the submit page to disable individual API subsections would be useful.
Reply
:iconmuteor:
muteor Featured By Owner May 6, 2014  Hobbyist General Artist
Yeah will make a note to look at response field lengths for the docs at some point.

With the API sections, in the future we will be using OAuth2 scopes, so you will be able to request more specific access. Currently the scope defaults to "basic", which is stash + userinfo, this is because we needed a way to support older apps that didn't use scopes. Again will make a note to look at splitting what is already there into more fine-grained scopes so you can choose better options for your app.
Reply
:icondahub:
dAhub Featured By Owner May 8, 2014
Thank you.  Do you have any comment on adding timezones to the whois endpoint?
Reply
:iconmuteor:
muteor Featured By Owner May 9, 2014  Hobbyist General Artist
No plans at this point but we will be looking at it in the future.
Reply
:iconbaronbeandip:
baronbeandip Featured By Owner May 6, 2014
The finner grained scopes sound like a great idea.  I'd love to see this implemented.
Reply
Add a Comment:
 
×

:iconmuteor: More from muteor



Featured in Collections

JOURNALS AND NEWS by Elandria

Articles and journals by Eitvys200

README.TXT by MidnightExigent


More from DeviantArt



Details

Submitted on
May 6, 2014
Submitted with
Sta.sh Writer
Link
Thumb

Stats

Views
28,074 (4 today)
Favourites
15 (who?)
Comments
44
×