dev: API Needs & Donations

[pradeep-rajapaksha]

No description provided.

[Chathula]

why don't we go with Laravel passport for API! we need to secure the endpoints!

if there is a authentication part in future, it is the best way i think. also we have oAuth support to secure API!!

[pradeep-rajapaksha]

Hi @Chathula, I think, at the movement its need to fast dev: So let's make this fast as we can.

[THPubs]

Can we get some sort of a api doc?

[pradeep-rajapaksha]

@THPubs, I'll send a google doc asap bro.

[sanathks]

You can use this service for your API doc. https://apiary.io/

[pradeep-rajapaksha]

Hi guys,
Here is the API doc that I created.
I tried with https://app.apiary.io and couldn't share with you cause it needs email. I'll update this doc more readable asap.

https://docs.google.com/document/d/1uQhqUhnAOYXzezLuMXyOpLdLNpzq5uC8UKT5ZKK1dbw/edit?usp=sharing

Please use this when my API code merges to the master branch and deploy it.

[pradeep-rajapaksha]

finally linked! 👍
https://github.com/pradeep-rajapaksha/reliefsupports.org/blob/master/apiary.apib

[gayanhewa]

I am not 100% on this, we already seem to have some changes that are basically the Donations API sitting under the namespace App\Http\Controllers\Api\V1 which is being used by the bot already. Please check the Gitter chat room if any of this work is duplicate and cross check against the existing endpoints. If all is good ping us and we can do a final review and get this merged in.

[pradeep-rajapaksha]

Hi, @gayanhewa
I've cleaned messed API code. Please check.!

[chamilad]

@pradeep-rajapaksha Few clarifications. The API doesn't seem to identify resources based on a unique ID. Is the document up to date? Since #46 is adding a unique ID for the entries shouldn't this API reflect that as well? Furthermore,

1. Should PUT ops be done against api/v1/entry/donations/{id}?
2. Shouldn't the document include error status codes as well? For example, PUT op for non-existent id?

[pradeep-rajapaksha]

@chamilad
I didn't get your idea in point.
But, there is key/column in db for needs and donations tables named "id". So, to get exact record; It used id to filter records.

api/v1/entry/ is just a prefix and entry word not related with EntryController.php. I used it cause It was there when I start.

Some of the mobile devs (Who I've met) do not use exact error status code in exceptions handling. They use only when an exception is true for the request success. Otherwise error.

That's why/what I have done here and please put your suggestions. It'll improve me. 👍

[chamilad]

@pradeep-rajapaksha Maybe what I have in mind doesn't directly map in this scenario. If that is the case, do forgive for digging deep :)

So as a dev, I'd like to first add a new donation record. So I'd do a POST call to api/v1/entry/donations with the required payload. On successful op, this will give me a URL to (say) donations/11. My questions are,

1. Can I do an update by PUT op on api/v1/entry/donations/11 with the same payload format as the earlier POST op?
2. Can I rely on the API to send me 400 Bad Request if I do a PUT on api/v1/entry/donations/13 which doesn't already exist?

I understand the point on devs not relying on too granular error codes, however, an API being just that cannot be changed frequently IMO. Otherwise, any changes to the API later would have to roll out new apps as well. So we might need to figure out the little details first, although, given the urgency of the situation, these could be looked over if others agree.

WDYT?

[pradeep-rajapaksha]

@chamilad
For 1, simply Yes! but, you can send only what you need to update. for now, it needs some different validations, I used same as POST.

When PUT op for records which dosen't exist, I've returned a response like this:
{ "error": true, "message": "Need not found.", "data": null }
but, Its not 400 Bad Request.

If any standard we can define for this, I can update the API asap.

[chamilad]

+1 to send 400 for relevant scenarios (ex: invalid PUT and POST ops). Otherwise, the API wouldn't be necessarily RESTful.

[pradeep-rajapaksha]

@chamilad, I got you! And made some changes. ;)

[chamilad]

Thanks! Shall we update the API doc as well? LGTM API wise for now. 👍