I'm attempting to create a REST API method that accepts multiple file uploads with some additional arguments. This API method will be called from both web forms, web services or mobile apps.
Is there a standard I should be following with regards to how the method takes these parameters in?
So far, I've considered the following two approaches:
JSON body: file data to be included as base64 encoded fields within the JSON object. Fine if being called from other web services, but troublesome when calling from a HTML form?
multipart/form-data: easy to use with HTML forms, but problematic when calling from web services or mobile apps?
I know that either of the two approaches would work, but I'd like to implement this the correct way (if there is one) according to current standards. Any ideas?
Do modern JS libraries/frameworks make it easy to POST HTML forms to web APIs as JSON objects
Yes, we have a lot of library to convert the file into base64.
In my opinion, choose what is based on your requirement. Firstly, exchanging data in multipart format should be more efficient than base64 json string. But this article show, the term of the size is little.
But if we use json, you could pass multiple other variable in the json format and we could read it easily.
Besides, if your file is image, the browser understand data URIs (base64 encoded images), there is no need to transform these if the client is a browser.
Related
From what I've seen, Google's Vision API lets you perform OCR on a PDF, but it returns only the detected text in a JSON format. What I need is a searchable (OCR'd) PDF file in return. Is this possible?
Notice that the OutputConfig type doesn't have any metadata field to configure the resulting file's format. As you are already aware, the API returns a JSON response. You could either first get the JSON data with the API and explore the use of any of the following repositories for JSON to PDF conversion or directly use any specialized module such as OCRmyPDF that specifically serves this purpose on your source PDF and avoid the use of the API altogether.
I'm implementing a RESTful API for what is essentially a document store, but am hitting a brick wall because I need a hybrid approach to one of the operations that can be performed on these documents.
Essentially, a user should be able to generate PDF versions of documents that are stored as JSON but also generate PDF versions of JSON strings that are passed arbitrarily (with no record in the database). The PDF reports never need to be stored anywhere, they are always generated on the fly.
My current API looks like:
/Documents
/Documents/1234
/Documents/1234?rev=4
Now, one way to implement the PDF generation would be to do:
/Documents/1234/Reports
or
/Reports/1234
But since we don't need to store PDFs (generated on the fly), both are reduced to only a GET operation, and it doesn't really act on a 'Report' object - which doesn't seem RESTful to me.
What complicates it further is that a user should be able to manually pass a JSON blob to the service and get a PDF. So something like:
/API/GeneratePDF
So does a separate stateless API make sense for this one operation? Maybe then redirect a request like /Reports/1234 to /API/GeneratePDF with the JSON blob for the 1234 document. It all seems a bit messy :)
The URL '/reports/123/' is pointing to a 'report' resource and it should not matter what backend operations will be acted on it.
When thinking about resource-url and its associated operations, the only relevant operations are "GET/PUT/POST/DELETE"
Then map the business operations (like generate PFD report) to the url+HTTP-Op+params.
Like in this case, map 'generate PDF report" to "GET /reports/123/"
use-case-1: simple get report
GET /reports/123/
return: {pdf-report}
use-case-2: customized report
GET /reports/123/
param: {"json info passed along with the get operation"
return: {pdf-report}
The the backend can detect if there are input from the client to decide what specific backend operations should be taken to generate the report.
Hope this help!
So I am updating a Play 1.2.x application with has the following setup
- controllers
- api
- Documents // create, update, read, delete, list
... // more controllers
- web
- Documents // list, read, etc...
.. // more controllers
The controllers in the api package render data as Json which is used by mobile clients (Android, iPhone).
Now I want to have a plain simple html web app consuming the api. So how can I consume the API from the controllers in the web package?
My goal is to avoid rewriting the api controllers logic in the web controllers logic.
Thanks!
Reusing methods between controllers is not the best practice in my opinion. Shared behavior should be coded in the model and both controllers can then use the same model methods.
Nevertherless if you want to do so, you can extract shared behavior in a public method in your apis controllers wich you can annotate as "#Util" and then call this method from your web controller.
There are not many details in your question, so I do not know if it applies, but usually when I implement REST APIs I let them serve their answers in different formats (JSON and HTML, and if you want JSONP and XML for instance).
The main idea is just to
check the request to know what format is required: either using the accept content type, the url extension, or even a parameter (and some more about it)
pick the right template (or skip a template if you have already correctly built your Json object)
In play there are different ways to do the first part, eg. through your routes: Request Content-Type in Play! Framework for REST webservices ; there is a specific page on Play documentation about this.
But the most important part in this answer is the second point: you should use the same controller and the HTML template should be able to render your page with the very same data that is sent back as json (or maybe a little more)!
NB. if you need to customize things a little more you can access the request object in the controller, check what the requested format is, and act accordingly to return appropriate data using the appropriate template!
I have a DESKTOP application which interacts with a web service through their RESTful api and OAuth 1.0. I can use all the resources fine, authentication, get/post calls to retrieve and send simple text data etc, no problems there.
However, I'm struggling to send binary data. The service allows sending pictures. For one part, they have a non-OAuth api through which you can also send a file in plain binary, simply pass some params in the URL and put the entire binary file in the post.
Now to do this through the OAuth api, becomes an issue:
The service specifies the post needs 2 parameters (not to be included in the URL since this is REST, but in the POST parameters):
image A binary file, base64 data, or a URL
type The type of file that's being sent in. Accepted values: file, base64, url
So we have 2 parameters: image contains the file itself, and type would be "file" to specify binary. But how am I supposed to include this through OAuth? given that the -image- and -type- parameters (and their values) must be used to generate the base string for the signature, which is matched against the parameters included in the POST.. I can't include the entire binary there as a value for the image parameter; so how is it done in this case?
nvm, their OAuth api expects the file as multipart/form-data with the variables there, and none in the base string for the signature (their non-OAuth api instead doesn't need multipart, so I expected their OAuth wouldn't either; their documentation is a bit lacking in this area).
I'm building my first Rest API which serialize data to JSON and XML formats.
I would like to provide an index page to API clients, where they would be able to choose implemented endpoints.
What information do I need to include to make my API most useful, and how should I organize it?
That's a very complex question for a simple answer.
You may want to take a look at existing API frameworks, like Swagger Specification (OpenAPI), and services like apiary.io and apiblueprint.org.
Also, here's an example of the same REST API described, organized and even styled in three different ways. It may be a good start for you to learn from existing common ways.
https://api.coinsecure.in/v1
https://api.coinsecure.in/v1/originalUI
https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid
At the very top level I think quality REST API docs require at least the following:
a list of all your API endpoints (base/relative URLs)
corresponding HTTP GET/POST/... method type for each endpoint
request/response MIME-type (how to encode params and parse replies)
a sample request/response, including HTTP headers
type and format specified for all params, including those in the URL, body and headers
a brief text description and important notes
a short code snippet showing the use of the endpoint in popular web programming languages
Also there are a lot of JSON/XML-based doc frameworks which can parse your API definition or schema and generate a convenient set of docs for you. But the choice for a doc generation system depends on your project, language, development environment and many other things.