Restful

[aussierhods]

Hello everyone,

Hope we all had a great NYE and Christmas .

 

Anyway - I'm seriously stuck - yet motivated to get an API on my site.

 

I am hoping a few of you can point me in the right direction based on my issues listed below.

 

I've tried to provide as much information as possible so you can see what I have tried and where I am comming from .

As a side note - any section I have doubts about what I am saying I have also put a ? next to the heading or text.

And please do correct me if I an wrong anywhere.

 

Background

I am attempting to make a PHP based RESTful API hosted on https://api.mydomain.com/1.0/ which would interact with a mySQL database and/or file storage.

The API once out of BETA would power the service itself - much like Twitter and be accessible externally through oAuth 2.0 connections.

Initially I wish to only support JSON and not XML.

• PHP
  
• MySQL
  
• JSON
  
• oAuth 2.0
  

References

These are the existing APIs I have been using as references when deciding how to construct the calls for my API.

• http://developer.linkedin.com/apis
  
• https://dev.twitter.com/
  
• https://developers.f.../reference/api/
  

oAUth Library

I will be using one of these two oAuth libraries:

1. https://github.com/fkooman/php-oauth
    
   
2. https://github.com/b...uth2-server-php
   

RESTful Operations as CRUD

From my understanding I have four HTTP methods at my disposal whic translate something like this (HTTP = CRUD = SQL):

• POST = CREATE = INSERT
  
• GET = READ = SELECT
  
• PUT = UPDATE (Modify) = UPDATE
  
• DELETE = DELETE = DELETE
  

Example URL(s)/URI(s)

So these are a few example calls I want to be able to make to test and trial this:

• https://api.mydomain.com/1.0/me
  (NB: me = current logged in user/user authenticated through oAuth)
  POST = ?
  GET = Get informaiton on current user, such as full name, age, etc
  PUT = Update information on current user, such as full name, age, etc
  DELETE = Delete current user
   
  
• https://api.mydomain.com/1.0/johndoe
  POST = Create a new user 'johndoe' ?
  GET = This would return data on a specific user - in this case 'johndoe'.
  PUT = ?
  DELETE = ?
  
• https://api.mydomain...es/254855781571
  (NB: Every file uploaded is given a unique number and this number is stored in a mySQL database which stores information against the file such permissions and a log of access.)
  POST = Upload file
  GET = Get file and display or download
  PUT = Change permisisons
  DELETE = Delete file
  

Sample of https://api.mydomain.com/1.0/me

So this is a sample of output from /me

{

"id": "1",

"name": "Jane Doe",

"firstname": "Jane",

"lastname": "Doe",

"link": "https://www.mydomain.com/janedoe",

"username": "janedoe",

"groups": [

{

"id": "98542514",

"name": "XYZ Inc."

},

{

"id": "105725",

"name": "ABC Rugby Club"

}

],

"gender": "female"

}

 

Much like Facebook does now I wish to use 'fields' to refine and join queries.

 

Sample of https://api.mydomain...e?fields=groups

So this is a sample of output from /me

{

"groups": [

{

"id": "98542514",

"name": "XYZ Inc."

},

{

"id": "105725",

"name": "ABC Rugby Club"

}

]

}

 

I understand that 'fields' could be acieved through https://api.mydomain.com/1.0/me/groups but this would not allow me todo https://api.mydomain...s=groups,gender

I hope and intend to support both https://api.mydomain.com/1.0/me/groups and https://api.mydomain...s=groups,gender style calls.

 

Detecting (Capture) RESTful Operations Server-Side ?

The next few sections are broken down a fair bit in seperate headings.

 

Obviously on the server-side (https://api.mydomain.com/1.0/) I need a file at index.php which handles/captures the calls made to the URL.

 

Now my understanding is that the oAuth library will generate and managed the 'access token'. Further my site (internally) should be able to use any API call without an 'access token' or will it need one itself?

 

So, anyway, start from the beginning .

 

What does the code look like the captures the calls made? And how does it handle the 'access token' in terms of knowing it needs one or not.

 

So as far as I can gather part of the code would need to determine the functuion (me, johndoe, etc) then the action (CRUD) and the informaiton that goes with it if needed by certain CRUD functions.

 

How would that code then process the function etc?

What code do I write to return user info etc as per the examples in the sections above?

 

Making the Call - Client/Developer Side ?

Finally what code does a developer use to call the API and get the data in a $variable as json. Again always assuming PHP.

 

End

As you can see I have tried to put a fair bit of thought and work into the post in a bid to show what i do understand and get some structured answers to help me out. But if anything makes nosense or needs clarification please ask and I'll do my best to clarify what I have written.

 

More specific questions on how to do the 'fields' may follow later if I cannot figure it out.

 

Thanks guys and gals.

 

I'm off to implement one of those oAuth libraries now

 

AussieRhods

Edited January 2, 2013 by aussierhods

[Christian F.]

Lots of good questions here, and it's clear that you've put a lot of research into this.

Even so, there are a few things I'd like to comment upon. Primarily it's your choice of adding the version number in the URL, which isn't exactly the best option. Not only is the version number of the API not a resource, but it also makes things more difficult for you to maintain. Instead use the HTTP headers to state what versions are acceptable, and base it from that.

Also, if you haven't discovered already, the Twitter API isn't exactly the best API to take as an example. They're not exactly RESTful, even though they claim to be. I had a really good video that showcased this, as an example of "what not to do", in addition to giving a really good walk through on how to make a proper RESTful API.

The last point is that JSON is only a good format if you control both endpoints. If you're planning on opening this up to the public, which I assume you are, then you really should be looking at XML. Reason for this is that XML doesn't break the old clients when you add new fields, like JSON would. Instead the old clients will just go happily on ignoring those fields they don't know about, while allowing the new clients to really take advantage of your API. All without changing anything in your code, least of all the URL.

 

In the interim, you might find the following article helpful:

http://www.infoq.com/articles/webber-rest-workflow

 

You don't have to support every verb for every resource, after all. Only pick those who make sense, and send a 405 for those requests which contains unsupported verbs.

 

When it comes to your "what code" questions: That's not something we can answer, it depends totally upon what you want. As for what code allows someone to access the API, it can be written in whatever language the client wants. That's what APIs are meant for, after all.