API documentation RAILS - ruby-on-rails

For my first API documentation (very simple API, only one method) I have more or less this structure:
API documentation
1.Disclaimer
2. Using the API
2.1 Input data -> Here I explain how should be the input data, JSON
2.2 Output data > Here I explain which data should be obtained and in JSON
2.3 Example -> I am giving an example of my input and output
In 2.3 I explain that the output (real example in my documentation, I post here only a structure of how it looks) should look like this:
{"message":"Succesful ","data":{"batt1":{"value1":977.48279000017,"value2":977.4208279000022,"value3":1034.9372639500002,"value4":2534.854048049996,"value5":2465.145176450681,"value6":2465.1451764508347},"batt2":{}...}
But its missing me how to put the request in this example.
Until now I have been using/ testing my API with this command: curl -i -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '#alldata.json' http://localhost:3000/api/v1/namecontroller
Should I put in my documentaion in 2.3 something like this:
In this example I used the cURL command in the following form: curl -i -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '#alldata.json' http://localhost:3000/api/v1/namecontroller
Sorry I am very new to all this, RoR,API etc...
Do you have any idea?

I think you can show it in below format so that will be easy to understand
url: http://localhost:3000/api/v1/namecontroller
method: POST
Body : #alldata.json

Related

JIRA REST API JQL query issue with maxResults

JIRA's REST API search doesn't honor maxResults parameter.
curl -o lambrusco.txt -k -D- -u admin:admin -X GET -H "Content-Type: application/json" https://jira.domain.com/rest/api/2/search?jql=assignee=blackpearl&startAt=0&maxResults=4
No matter what maxResults is, it always returns 50 results.
Output:
{"expand":"schema,names","startAt":0,"maxResults":50,"total":61,"issues":[{"expand":"operations,versionedRepresentations,editmeta,changelog,transitions,renderedFields","id":"15588","self": ...}
What am I missing here?
Your request looks fine. Here is example on official Atlassian JIRA, which works fine:
curl -X GET -H "Content-Type: application/json" "https://jira.atlassian.com/rest/api/2/search?jql=assignee=tlay&startAt=1&maxResults=1" | jq -r '.maxResults'
It looks like that it's related to REST API Bug!
You need to quote the request when using curl as shown by #grundic, otherwise the shell will interpred the ampersand. And note that the API is case sensitive.

Swagger UI generating wrong Curl command

Swagger UI generating wrong Curl command as pasted below and due to this query string truncating
curl -X GET http://domain:8080/v1/endpoint?access_token=affsfafasfa&type=1 -H "accept: application/json" -H "content-type: application/json"
the correct Curl command should be like this
curl -X GET 'http://domain:8080/v1/endpoint?access_token=affsfafasfa&type=1' -H "accept: application/json" -H "content-type: application/json"
the difference between above two command is quote around http url . So please tell me how to achieve this in swagger ui ?
I guess you found a bug in the new version. The very latest code already contains a fix for it.
Its an bug in swagger ui version 3.0.2 and swagger support team has fixed this bug now https://github.com/swagger-api/swagger-ui/issues/2839

curl POST request empty in ZF2 Rest API

I am testing my ZF2 Rest Module that is running on localhost, by sending curl POST requests from the same box.
curl -i -X POST -H "Content-Type: Application/json" -d '{username":"xyz","password":"xyz"}' http://localhost/api/login
In the corresponding controller and action, I have tried returning the POST parameters, but an empty array is returned always
var_dump($this->getRequest()); // returns: array(0){}
var_dump($_POST); // returns: array(0){}
If I switch from POST to GET with
curl -i -G -H "Content-Type: Application/json" -d '{username":"xyz","password":"xyz"}' http://localhost/api/login
it actually seems to work
var_dump($_GET); // returns: array(1) {["{"username":"xyz","password":"xyz"}"]=>string(0) ""}
Why is the POST request failing to pass/extract the parameters?
PHP only populates $_POST for form urlencoded POST data. You've explicitly set the content type to JSON, so the PHP way to access this would be:
file_get_contents("php://input");
In ZF2, I believe you want:
$this->getRequest()->getContent();
and in practice, you'll probably want to run this through json_decode().

How do I make OmniAuth Identity accept JSON post data?

I'm using OmniAuth-Identity for log ins, and logging in using Ajax calls. Attempts to log in passing JSON data don't work.
For instance this works:
curl -i -H "Accept: application/json" -d "auth_key=joe#example.com&password=cheesestix" "http://0.0.0.0:3000/auth/identity/callback"
This doesn't, it returns "invalid credentials"
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -d '{"auth_key":"joe#example.com","password":"cheesestix"}' "http://0.0.0.0:3000/auth/identity/callback"
Is this a known issue? Form encoding my data will be difficult as I'm using AngularJS.
UPDATE:
One of the rails guys fixed it by backporting JSON support into Rack.
gem 'rack', git: 'https://github.com/ssoroka/rack.git', branch: '1.5.2-json-support-backport'
I'm hesitant to post that as an answer becase I don't understand the details of Rack well enough to explain anything. But the relevant diff is here: https://github.com/ssoroka/rack/commit/d8e2e2af6da57805d2f0906ce925ea150def31a0

curl - request with json object and file to Rails API

I need post file and JSON object to API (Ruby On Rails) by curl in one request.
My request looks like this:
curl --data #file.pdf -H "Accept: application/json" -H "Content-Type: multipart/form-data" -X POST -d '{"document":{"name":"file name"}}' http://localhost:3000/api/documents
But Rails parse it bad. Params on the server:
Parameters: {"{\"document\":{\"name\":\"file name\"}}"=>nil}
Where is problem?
You should pass multipart/form-data (as you specify), not a JSON string. Try this:
-d 'document[name]=file name'
Result on my machine:
Parameters: {"document"=>{"name"=>"file name"}}

Resources