For a few weeks, I've been trying to gather as much information on implementation of RESTful apis in PHP as I can but in vain. All the information that is given online only explain the most basic concepts but never did I come across a very real example with complete code on how RESTapi actually works.
For Example, POST is used create a new resource. But how? How is it implemented in real life? How do I do this in cURL? I am aware of the complete basics but am unable to find any concrete and complete example that explains everything. Most of the tutorials simply name the functions they've used but did not bother explaining what is happening exactly, what the flow of the program is, etc.
If someone can help with a complete example (say, a library registration and database) I'll really appreciate it. I'm really confused.
I will describe POST method in REST.
Client send HTTP request via POST method with JSON data.
For example, client send some data to create a word "nice".
POST http://localhost/word/1
JSON content
{
"data": {
"type": "word",
"attributes": {
"word": "nice"
}
}
}
In PHP you need get a response and convert to array and insert ot DB. Why insert? Because request method is POST.
Related
I am working on a project where I am trying to expose the function of the software. Basically I have my backend set up and was thinking of seperating the frontend from the backend code using JSON msgs. I am a little bit confused as to what is the difference between a service and an API. I know API can be build on top on services. But I have these two models in mind -- to access profile X using json-rpc
http://xyz.com/?request={"jsonrpc":"2.0","id":1,"method":"getProfile","params":{"id":"X"}}
or should it be like this using REST -
http://api.xyz.com/X
Thank You
"Service" vs "API" is a pretty vague question. Often, the two terms are used interchangeably. "REST" vs "RPC" is a little easier to explain.
Usually with REST, a URL represents a specific resource such as a "user", an "account", etc.. Typically, you can create/retrieve/update/delete these resources by using the HTTP methods POST/GET/PUT/DELETE. To update the profile for user 1125 you might send the following:
POST /user/1125 HTTP/1.1
Host: wherever.com
Content-type: application/x-www-form-urlencoded
firstName=Davey&lastName=Jones&email=dj%40thebrineydeep.com
Anything you wanted to do with user 1125, you would send a request to the same URL. There are exceptions and variants of this idea, but that's the crux of it.
RPC services is more like just using a function library, which is bound to a specific URL. You might have a whole bunch of related functions all bound to the URL /services/json. Then if you wanted to change the profile for old Davey Jones, you would:
POST /services/json HTTP/1.1
Host: wherever.com
Content-type: application/json
{ "jsonrpc": "2.0",
"id": 1,
"method": "setProfile",
"params": [ 1125,
{ "firstName": "Davey",
"lastName": "Jones",
"email": "dj#thebrineydeep.com"
}
]
}
I personally like JSON-RPC better because:
I don't have to try and fit all of my function calls into some kind of resource-to-url mapping that might not make sense
We don't try to overload the HTTP response codes to indicate API errors. Every request returns a 200 response (unless there is a server error) and you know from the response body whether you got an error or not. JSON-RPC is particularly good at being explicit about error conditions.
Sometimes REST is better because:
Sometimes the resource-to-URL mapping fits really well
It is more intuitive for third parties to understand
It offers a simpler model for just retrieving easily-identified information
I don't think either one is any easier to code.
Edit I changed the REST example to use the more common form-encoded data instead of JSON. But of course you can specify any data format you like with REST. It isn't carved in stone.
Your REST URL does not equal your JSON-RPC request.
At least it should be http://api.example.org/getProfile?id=X
There really is not much difference between the two. And your "REST" isn't a real REST unless you return a data format that reliably can express links to different URLs, e.g. XML or (X)HTML. Until this requirement is met, you should only call it "RESTful", because you really only use HTTP methods to trigger stuff and move data back and forth.
It doesn't really matter what you use - unless you know or have experience with software that supports you building one or the other solution more rapidly than the other.
I've been reading a few REST tutorials and some of them says that in order to send data to a rest API you should send post data as an array, which is something like this:
$data = array('foo' => 'bar');
$rest->post($data);
Then there are others that say you should send JSON data like this:
$data = array('foo' => 'bar');
$data = json_encode($data);
$rest->post($data);
Not sure if there's a standard way of doing this or either if is fine but what is generally recommended when designing API's?
EDIT: There seems to be confusion. To clarify I agree JSON should be used for client consumption but this question is about SERVER consumption. Meaning should the SERVER accept JSON or POST data from its clients?
If you're the one creating the RESTful API, meaning your application is the server and is accepting requests, then your question seems confusing. Your application will not be sending any POST data; clients will be sending POST data to you.
With that being said, having an API which will accept JSON-encoded requests is possible, though would really only be useful for very niche scenarios. The vast majority of clients will be POSTing data to your API in the application/x-www-form-urlencoded format. PHP handles this behind the scenes for you, and exposes the data as the $_POST superglobal.
If you're talking about responding to POST requests, and what format you should use, then that will depend on what format the client wants you to send it in. The client will either specify this in the Accept header, or some APIs allow it to be specified in the URL (e.g. foo.com/some/thing/123.json or foo.com/some/thing/123/json). The client isn't required to tell your application what format it wants, so it's up to you to pick a sensible default. Most APIs will use JSON these days.
I've never heard of an API that understood serialized PHP array format, though, so I don't know what resources you've been reading, but I'm pretty sure you misunderstood what they were suggesting.
Actually, I think this is a pretty good question. don't know why it got downvoted.
Also, contrary to what I saw written in some comments, the client can use any language he wants, not only javascript. And it's not the server job to know which language was used to "build" the request, just that the request is valid. This makes more sense if you think that the entity making the request can actually be another server (think about a proxy server used to send post requests across domains).
That being said, personally, I think it's better for the server side to consume a XML or JSON. The main reason is validation.
It's easier to validate a XML or JSON against a schema.
Also the schema can be made public, and a well designed schema can describe webservice by itself. The client can even use the same schema to validate the request prior to sending it to the server.
Passing an url encoded form is also valid, of course. And can be validated server side as well. SO i think, down the road, it's just a matter of preference.
Also, check this discussion in SO, it regards the same topic:
JSON vs Form POST
You should think about the clients that will consume the API. A HTML5\AJAX client will probably want JSON data, while other clients (Silverlight or native mobile apps) might be better at consuming XML.
One great framework\platform for writing REST API's is looking to be Microsoft's Web API (based on ASP.NET MVC). The product succeeds the WCF framework and allows users to write REST API's in a MVC environment. One feature is that it chooses a serialization provider based on the HTTP Accept header.
So if a client Accepts application/json they work with the service in JSON and if the accept XML they work with the service in XML. You can also write your own object serializer and plug it into the framework.
More information: http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/video-your-first-web-api
Most of the time you would want to stick to receiving POST data but I think receiving json data does have its uses for example when it comes to batch requests.
The Facebook API uses it.
You don't need to do file_get_contents('php//input'). From the facebook documentation you could just do something like this:
curl -X POST "http://example.com/batch" -d 'batch={ "param" : 1, "param2" : "2"}'
Then in the PHP code, if you're using PHP, you can get it through the $_POST parameter and do a json_decode.
var_dump($_POST);
array(1) {
["batch"]=>
string(30) "{ "param" : 1, "param2" : "2"}"
}
var_dump(json_decode($_POST['batch'], true));
array(2) {
["param"]=>
int(1)
["param2"]=>
string(1) "2"
}
JSON makes more sense, since it is language-independent and can be useful when API scales.
I am currently developing a REST API and I was asking myself the same question. After some research I found out that is no standard and is totally up to you.
You are developing the server side so you can decide how data should be sent to you. The client need to adapt to your design.
Personally I choose to receive all POST and PUT data as JSON directly in body.
The point is to reuse the HTTP implementation that already exists.
HTTP is built to accept many different content-types and you only need to specify which you are using in the headers.
A REST API that accepts the various formats and works off the content-type header is refreshing. You can submit x-www-form-urlencoded values from an HTML webpage or make an AJAX request with raw JSON and there is no confusion as long as everyone is following protocol.
As a developer you must choose the support your app will provide because you can't support everything. Typically it boils down to the support or convenience of your own environment -- nobody wants to reinvent the wheel.
Many frameworks that are designed with building APIs in mind, handle the most popular content types at a lower level. They may also encode the response data according to the "Accept" header.
Implement whatever you think will be used most first or find a framework that already speaks HTTP and takes care of all of that for you.
Sorry if this is too remedial or repetitive in any way but I need some advice. I'm a PHP guy and I've been asked to create a container-type app to capture our yahoo! store orders data, which is sent as xml using this DTD:
http://help.yahoo.com/l/us/yahoo/smallbusiness/store/order/retrieve/retrieve-20.html
The Y! Store wants us to specify a URL on our web server to send the XML data to, and here is their example:
http://lib.store.yahoo.net/lib/vw/OrderList.xml
But am I missing something here? I've worked with simplexml_load_file() to parse XML files. But what do I need to build a web service here? How do I GET the data? I'm not even sure if Y! is sending it as a POST or how to validate it.
Do I need additional documentation on their end? If anyone can point me in the right direction, I'd appreciate it.
Thanks in advance,
-Bob
I'm never one to answer my own questions but I just thought I'd leave this for someone else some day down the road, considering Y! isn't the best with documentation on this.
The orders export from Y! Store is straight XML, not SOAP. If sent to an Apache server, you're in luck -- it's a simple $_POST. So all you need is:
$variable = file_get_contents("php://input");
In my case, however, things were complicated with IIS so I had to add HTTP verb, open up the folder permissions, etc.
-Good coding, all
Being a PHP guy have nothing to do with understanding webserves. Webservices isn't really have a POST or GET, it sending an envelope (XML), and expecting a response, also in XML.
You need to learn how to use SoapClient on PHP, here is a good place to start:
http://php.net/manual/en/soapclient.soapclient.php
Validation is something you do before sending the soap request, and validation of what is being sent back from Y! is also done by you. Hope this help you get started.
I have spent the past three days researching this... but Im still stuck.
I have a service provider that offers me a REST api. I need to:
Get the data from his api
Assign the data to variables in php
Write the data to my localhost sql database.
All that's required is the API KEY which has been provided to me.
Please could someone explain to me what method I should use to call and store the data in php.
Writing to the Database and handling the data once in php format is not a problem.
Thanks in advance
Since you want to consume a webservice you would have to make HTTP request using PHP.
There is many ways to do that but the most used(IMHO) is cURL. cURL function would allow you to easily make HTTP request and consume data from the webservice.
I'm creating a webservice in which remote sites can send data to a PHP-based webservice. However, I'm struggling to come up with the best way of handling the incoming data.
The data will be in the form of shopping basket contents, so might include product name, price, ID, date, customer etc. There will be one line of data for each product in the basket, so there could be 20-30 lines for some customers.
Would sending the data to the webservice via GET be sensible? Is there a better option you can think of? Any input is greatly appreciated.
Thanks!
Probably not a great idea to send via get. I'd generate the basket as XML or JSON, then post it to the service. You can then write back a response on XML or JSON saying whether or not the call was successful.
A nice introduction to a RESTful API with PHP is here. I find it goes a bit overboard in some places, you can do the same with a little less code but it is nonetheless a good guide.
If the request is going to be making a change, I would not use GET. It would break GET's safety. Here's the HTTP spec on safe methods: RFC 2616.
I would recommend you look towards a REST architecture where it seems like a POST or possibly a PUT request should be used.