Current Status of using Services

After our awesome discussion today at the mid-west developers conference, here are the issues I'm running into trying to build a social media platform REST interface (for an iPhone app) with the current Services set up:

Current Issues:

• Lack of consistency of interfaces

  This could be broken down into separate points, but here are some specific examples:

  1. POST/GET format differences

     GET /{endpoint}/node/{nid} returns:
     {"nid":"1","title":"this is a node", "body":"....." etc}
     -- but --
     POST /{endpoint}/node requires (value/pair):
     {"node":{"title":"new node", "body":"...." etc} }

  2. POST return differences

     POST /{endpoint}/node returns:
     {"nid":"961","uri":"..."}
     -- but --
     POST /{endpoint}/taxonomy_term returns:
     0 (yes not wrapped in JSON)

  3. Update User inconsistencies

     Updating a user requires the machine calling PUT /{endpoint}/user/{uid} to know whether they are updating basic user info (mail, name, password) or profile information. For example, if you were updating mail you would PUT:
     {"mail":"a@a.com", "username":"", "password":""}
     If you want to update profile information:
     {"category":"profile", "profile_first_name":"", ...}

     This should really be done in such a way that I can send Drupal only the data I want to update (let's say mail and profile_last_name) and it just updates it (if possible or you have permission, etc).

  4. Field inconsistencies

     In order to login, you POST:
     {"username":""}
     In order to create a new user or update an existing one you POST:
     {"name":""}

     It would be nice if this was one or the other. Are there security implications with this though?

  5. Contrib implements their own paging

     This may be scope creep:
     For example, the private messaging module (privatemsg) uses offset and limit; instead of page and pagesize

• Full Views Integration

  Some modules don't show up in the current services_views implementation. An example is Vote Up/Down (vud_node) 6.x-2.8.

• HTML Markup in fields:

  services_views returns body fields with HTML tags. This is using the default of FALSE for rendering theming. It leads to a general question of should tags be allowed to be part of the final output (otherwise you lose words that were bolded, etc)? Should there be a checkbox for that interface to do this?

• Ability to only show certain fields

  It would be nice to be able to select what fields get returned to the client.

• Service Users

  Let's say I have a remote machine that needs some sort of basic access (list of users, etc). It would be nice to be able to create a key that can be passed in the arguments (or proper IETF Standards) instead of authenticating as user. This would eliminate the need for service user roles and accounts strictly for remote machines to get access to limited information. Given the security implications of this, see item 1 below of what Services currently does well below:

Current Good Solutions:

Here are some awesome things that Services does well right now:

• Ability to create separate endpoints

  This is a huge plus on the current Services module. Doing this allows us to create endpoints that have limited abilities, so that if packet sniffing did occur and someone did find an interface, they could only do limited things on the interface they found if they have an account or sniff that information as well. I typically use this in combination with a service user for each type of remote machine that needs access.

• (Limited) versioning of endpoints

  Currently, you are able to (admittedly somewhat limited) create an infinite number of custom endpoints. So, if you created a basic iPhone app with some custom endpoints, and named your service awesome-v1, then later you needed to update the custom endpoints, you can create a new module, change your code, and then create a new service awesome-v2 using the new code for the endpoints. This allows you to cleanly transition as clients slowly upgrade.

Services Long Term Solutions:

• Here is what Services is trying to do in the long run for versioning of APIs:
  http://drupal.org/node/1436366

WSCCI Long Term Solutions:

• Consistent Contrib Interfaces:

  This is easily the biggest issue that makes the interface professional versus look hacked together.

  Somehow we need to think of a way that contrib modules can easily create custom endpoints and provide things like consistent paging, proper error formatting, etc. It would be ideal to have a review process where contrib maintainers can get feedback/help on the proper ways to implement things. At a minimum, examples of how to properly create interfaces need to be very well documented.

• Date/Time:

  We take this for granted when Drupal to Drupal talking goes on, or another system is *nix based, but is the Unix Epoch GMT/UTC time the standard format? (most likely answered by JSON-LD standard)

• Limit endpoints by role

  It would be huge and awesome if we could limit endpoints or APIs to be locked down by role or specific users. Combining this with locking down endpoints resource abilities that Services currently has would make for a safer way to open up interfaces.

• POST: return IDs

  This may go against IETF or JSON-LD standards, but if so I would support it. It's great that a remote machine receives a constant response of success or failure from proper response codes, but often I'm expecting to know not only what I submitted was created successfully, but also how I can reference it (NID, UID, TID, CID, FID etc). Often, when creating sub-items, machines are planning on using these IDs to submit with a new node.

• multipart/form-data

  Services currently does this, but the only reference (and developer I've seen using this) is here in the issue que: http://drupal.org/node/1270190. However, this is huge! I've had issues when developing for Android where the system had so little memory available that base64 encoding a file would cause the app to crash.

• Ignore Theming

  Because current Services renders through the Theme layer, the theme can inadvertently disrupt the API consistency by storing something, such as gender with 0 or 1 in the DB, and using an if statement to render it as Male or Female to users. Thus, PUT requests use 0 or 1, but GETs return Male or Female