Prestashop: REST API full documentation and error codes

[LucaMozzo]

Is your feature request related to a problem? Please describe.
I'd like to start by saying that I develop enterprise RESTful APIs as my full time job. What Prestashop lacks is a proper maintained documentation on REST via HTTP. Only a fraction of people using the webservice are using PHP and so far I had a bad time understanding how the API works.
Whatever body I PUT or POST I get a 200 and the list of resources, so the method is completely ignored (even though PUT and POST are enabled for that API key).

Describe the solution you'd like
I'd like to have a proper documentation of the REST API, rather than the PHP wrapper. There are tens of unanswered questions on the forum because no one has the resources

Describe alternatives you've considered
There is a CRUD tutorial that is useful for the GET requests, but no clue on PUT and POST

Additional context
All my doubts at the moment are around the correct way to authenticate (is using the trailing query parameter for the key the way to do it for all HTTP methods?) and basics on how to perform the request. Additionally it would be good to know if the API accepts JSON formats as body of the requests (since JSON is supported for output). I'm using v 1.7.5.0 but it would be good to have a versioned documentation as for the other tutorials.

Thanks

[khouloudbelguith]

Hi @LucaMozzo,

To get more information about webservice in PrestaShop, you can follow this link.
Also, you can follow our documentation: http://doc.prestashop.com/display/PS16/Using+the+PrestaShop+Web+Service
You can found some examples in our GitHub repository: https://github.com/PrestaShop/PrestaShop-webservice-lib
Thanks to check & feedback.

[LucaMozzo]

Hi @khouloudbelguith
Thanks for the resources. I have a couple more questions that are not covered there:

• When I use the browser to go to http://[email protected] I'm still asked for BasicAuth, which is forcing me to use the query parameter ?ws_key=KEY instead. Is that correct? can the query parameter be used with POST and PUT?

• Can I POST and PUT JSON objects?

• The PUT url is /api/resource/id and the POST one is /api/resource. Am I correct?

Thanks

[matks]

What Prestashop lacks is a proper maintained documentation on REST via HTTP

We are unfortunately aware of that 😥 however we have a huge pile of tasks to do to improve the project and make it evolve in the right way (as I'm writing now, there is 978 issues, so as you can see we are quite busy 😛 ).

However this is an opensource project so please consider contributing to the project 😉 you have a good knowledge of what this documentation should contain and look like. Would you write down your suggestions ?

Now that I'm thinking of this, probably https://github.com/PrestaShop/docs is better suited for this

[eternoendless]

When I use the browser to go to http://[email protected] I'm still asked for BasicAuth

This is a security feature that each browser implements differently. In Chrome, you'll be asked for a user and pass, just write the key as the user and leave the password blank. This won't happen when you use curl for example:

$ curl http://[email protected]/api/

(server response)

Can I POST and PUT JSON objects?

No, the API only supports XML on input but supports JSON output if you choose so:

http://[email protected]/api?output_format=JSON

The PUT url is /api/resource/id and the POST one is /api/resource. Am I correct?

That is correct.

[LucaMozzo]

@matks I'm not aware of PHP API doc generators, but in general do you accept PRs from forks (i.e. if I create a fork and open a pull request will it be considered for review/merge?)? I would be happy to contribute since I see many people having this problem and I'm happy to put something together

@eternoendless thanks for your clarification. I was trying in Postman but it was behaving weirdly (i.e. returning 200 despite not making the change), I might try implementing that directly in code

PS: it's a shame that the technical documentation didn't come up un the first 2 pages of a Google search because it answered half of my questions!

[matks]

@matks I'm not aware of PHP API doc generators, but in general do you accept PRs from forks (i.e. if I create a fork and open a pull request will it be considered for review/merge?)? I would be happy to contribute since I see many people having this problem and I'm happy to put something together

Yes we accept PRs from forks, actually this is the standard way to contribute to PrestaShop project 😉 we will be very happy to review/merge your contribution

[LucaMozzo]

Perfect, thanks a lot!

[khouloudbelguith]

@LucaMozzo, feel free to open a new issue when needed.
Thanks!