We have an API end point where an image file can be uploaded along with the name of the file (a string) as well as a description (string).
Apiary / API Blueprints won't allow me to have something like:
+ Request (multipart/form-data)
+ Headers
Authorization: [key]
+ Attributes
+ name (string, required) - A human-readable name of the Catalog Item
+ description (string, optional) - A human readable description of the Catalog Item
+ image (file, optional) - An image file corresponding to the Catalog Item
I get:
base type 'file' is not defined in the document
Is there a way to represent multipart/form-data such as the above in API Blueprints?
Related
In my blueprint I'm defining a data structure and try to use it like so
+ Attributes
+ error: (Error Details, required)
Data structure definition at the end of the document:
# Data Structures
## Error Details
+ code : 1234 (number, required) - see list of error codes
+ message: User not found (string, required) - a human-readable error message
The resulting sample response body looks just like expected but the validation on apiary.io shows semantic issues for each of the places where I use constructs like this, saying "No value(s) specified".
Am I doing something wrong or is it a problem with the apiary.io parser?
I had the same problem and solved it by
omitting the colon
separating the object definition and type (see owner in this example):
Company (object)
name: Company name (string)
owner (OwnerResponse) (object)
A similar answer to other current answers, but none the less this fixed it for me.
No good:
+ Attributes
+ `status`: OK
+ `data`:
+ 5 (Channeldata)
+ 7 (Channeldata)
Fix:
+ Attributes
+ `status`: OK
+ `data`
+ 5 (Channeldata)
+ 7 (Channeldata)
As others have noted, losing a colon in the right place can fix things.
Attribute section can be also defined as + Attributes <Type Definition> (specification), so defining + Attributes (Error Details, required) should fix the given semantic issue.
Edit:
You have to omit a colon between attribute's name and its type, when an example value is not defined:
+ Attributes
+ error (Error Details, required)
Missed that before, sorry.
Consider this excerpt from https://github.com/apiaryio/mson#example-1 ...
Example 1
A simple object structure and its associated JSON expression.
MSON
- id: 1
- name: A green door
- price: 12.50
- tags: home, green
Let's say I would like to define valid values for the name attribute. Consider a context of API testing with a tool such as Dredd. We may need to define what are the expected/valid name values in response to GET'ing this resource, or else something is probably broken and this test step should fail.
And/or, if creating/updating a resource of this type, we may need to define what name values are valid/accepted. Is this currently possible to define in MSON?
(I believe this can be done in a JSON schema, which makes me hopeful for MSON support.)
Following is an example API Blueprint resource to illustrate how this would be used...
# Thing ID [/api/thing/id]
# List Thing ID attributes [GET]
+ Response 200
+ Attributes
+ href (string)
+ make (string)
+ model (string)
+ version (string)
+ Body
{"href":"/api/thing/id","make":"BrandX","model":"SuperThingy","version":"10.1"}
In the above example, there are 3 known/accepted/valid values for the model attribute: CoolThingy, AwesomeThingy, and MLGThingy
Can we represent this resource in MSON, such that...
Apiary (or other rendered) API documentation consumers can easily know what model values to expect?
Dredd processes and passes/fails the model value in the response to a GET to this resource?
In MSON you can use enum, see the example below.
name (enum[string])
joe (default)
ben
mark
I'm documenting a public API that has a method named /findGuild that takes a mandatory key parameter and one of the following parameters:
byPlayer
byName
It must have either byPlayer or byName; My question is: How do I indicate that byPlayer and byName are mutually exclusive, but one is mandatory?
Right now, I have the following in my .apib for this Resource:
### GET /findGuild{?byName,byPlayer,key}
+ Parameters
+ byName: `YourGuild` (string, optional) - Search for the Guild by its name.
+ byPlayer: (string, optional) - Search for Guild by a player. Does not seem to work.
+ key: `ffffffff-ffff-ffff-ffff-ffffffffffff` (string, required) - The user's API key.
+ Response 200 (application/json)
+ Attributes (object)
+ guild (string) - The guild id or null.
+ success (boolean) - Should be true.
+ Body
{
"guild": "ffffffffffffffffffffffff",
"success": true
}
I am afraid (but not totally sure) API Blueprint is not capable of expressing this kind of relationship at the moment.
What I can surely tell you is that, according to public roadmap, URI Parameters will be replaced with an MSON object, which supports the scenario you're asking for.
Hope it helps!
When writing an API-Deocumentation for an rest-service I came across an problem where I wanted to list all the possible Values which could be returned as a response.
In the case below it would be the "state" field which could contain any possible value of a enumeration and I wanted to sum up which possible states there are.
I could not find an easy and nice way to do it with apiblueprint. Is there a way to display sections collapsed by default and expand them when additional information is needed?
Here is the Sample code I have:
## Sample [/Sample?{id}]
Get all the information for the sample
+ Parameters
+ id = `0` (Integer, optional) ... The Id of the resource to get
+ Model (application/json)
+ Body
{
"name": "Name of the Resource",
"state": "deleted"
}
### Retrieve the sample data of the system [GET]
+ Response 200
[ProviderConfiguration][]
I need something like "Values" for the parameters section but for the Body part to describe the state in the Body section e.g.
<collapsible>
+ state (EnumType) ... current state of the sample object
+ Values
+ `active`
+ `inactive`
+ `deleted`
</collapsible>
Unfortunately, this is not yet possible with API Blueprint. However, it's planned - see https://github.com/apiaryio/api-blueprint/issues/25 and https://github.com/apiaryio/mson.
Everyone keeps talking about opening the attachment. IT'S NOT AN ATTACHMENT! The image was pasted in a rich text field in Notes cocument. When I view the properties of one these Notes documents with the image, (unfortunately I'm not able to paste images to this), there are internal fields created for this rich text field namely MIME_Version, and the name of the rich text field listed four (4) times as shown below:
Field Name: myImage
Data Type: MIME Part
Data Length: 141 bytes
Seq Num: 3
Dup Item ID: 1
Field Flags: SIGN SEAL
"Content-Type: multipart/related; boundary="=_related 006391B688257C0D_="
This is a multipart message in MIME format.
"
___________________________________________________
Field Name: myImage
Data Type: MIME Part
Data Length: 150 bytes
Seq Num: 3
Dup Item ID: 2
Field Flags: SIGN SEAL
"--=_related 006391B688257C0D_=
Content-Type: text/html; charset="US-ASCII"
<img src=cid:_2_0BCE1D8C0BCE1ACC006391B688257C0D>
"
____________________________________________________
Field Name: myImage
Data Type: MIME Part
Data Length: 14064 bytes
Seq Num: 3
Dup Item ID: 3
Field Flags: SIGN SEAL
"--=_related 006391B688257C0D_=
Content-Type: image/jpeg
Content-ID: <_2_0BCE1D8C0BCE1ACC006391B688257C0D>
Content-Transfer-Encoding: base64
/9j/4AAQSkZJRgABAQEBLAEsAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYIDAoMDAsK
CwsNDhIQDQ4RDgsLEBYQERMUFRUVDA8XGBYUGBIUFRT/2wBDAQMEBAUEBQkFBQkUDQsNFBQUFBQU
FBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBT/wAARCACtALUDASIA
AhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQA
AAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3
ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWm
p6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEA
AwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSEx
BhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElK
U1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3
uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwCl8fZ1
g+EHweXjJe9yP++a9D/ZGne78WMAuFS1k5H+7XK/tD+GLI+D/hHph1q2mhX7YEv4Y5PLlORgBSN3
6V7R+yr8K18Pajcag2prcMsBTyzZzxHnp8zoF7V6ftDy1TPzv0IkRKW616n8OxibUyx4Ol3i5P8A
1wcVwvg7wqddHmR3cUDCYoY2DEgeuAK9s8O+B/8AhGbLUrj7fbXskmm3qrEquGGLaRt3IHoB+NTG
pyvUfszx3wrue8h2hiSw4U+9e8ftoH7V8IfhRHDIhaP7QJFHBB2rgGuA+FPwxudXl0+5TU4IoZUR
hI6tjPHGQD34r179vrQX8P8Aw0+GWmySRzyCWVnnhz02L6/UVtGqheyZ80fDsGDVdNVmwVmjJwen
Ir7L/bg1a11b4f2lzb3CShbqziG3IBIikJ57187fCb4b6fq2s6WG1Ro90qLs+ySuScjj5VPqK+h/
28dOh0z4W2UcChUXW4I1O3acCCbqKUaqZo6bSPkXww2zWrJiSFVweK/SafWrTV/2YdcMc4M0Oi3O
4OCNp8pvUV8DeB/hpd6qNMvItRtUWbDYYnK8nGQB7V96+Mb638Ffs26nol/fQHUbvQ544j03u0TA
AfXIFTKaM1Tkmfnt4G+IGveGdKgtNP1CS3gBV2REU4P4g19s/BPxfr/i7QhaXWsieAoGdJYwOPqF
r4w8A+Gx5tyJSB5iFFDdB/tfhX3h8BLC38IeHEWeePdMAkUBfLk+pFTGojRxZ8L69qN5ZfF3xMtt
eT2y/wBq3IPkyMmfnPoa6n9pLU5bz9muKKa5muGGq2pXzZC3c9M1VTwS/ir4sa5KNQtrGefWbkLD
O3JBkOD+Ndd+1t4OGjfs8aZGtzDeM2qwljbHdjrSvFu4JSPEfh3ezQarAI7qaFRgARyFR+hr1b49
X9wNM8GTx3U5mUODL5h3jjpnrXJ/CP4Zt4ivLdYdUgicIhcPG52Eg8Eqp9K9W+PngBjfeFfD41K2
aeOKT94iMQHUnIIxnPHpRzxW4+STPO ..."
_________________________________________________
Field Name: myImage
Data Type: MIME Part
Data Length: 54 bytes
Seq Num: 3
Dup Item ID: 4
Field Flags: SIGN SEAL
"--=_related 006391B688257C0D_=--
"
Can someone please let me know how to display this image saved in a Notes document, in Xpages. What type of XPages control should be used? Thanks in advance.
You can use simple data binding to bind to a Rich Text field in the current document.
In my case binding to document1 a field called OverviewPicsChildparts which contains a pasted image works fine.
However I am trying to display a pasted image into a repeat control whose source is a DocumentCollection of response documents to document1 which is not as straight forward it seems.
However I solved this by adding this code...
<xp:this.data>
<xp:dominoDocument var="doc"
action="openDocument"
documentId="#{javascript:AllResponseDocs.getNoteID()}" ignoreRequestParams="true">
</xp:dominoDocument>
</xp:this.data>
Into a panel inside the repeat control and then was able to use Simple Data Binding binding to doc the field I wanted like this...
<xp:inputRichText
id="inputRichText1"
value="#{doc.ProPicture}"
readonly="true"
style="width:198.0px;height:141.0px">
</xp:inputRichText>
it worked for me.
As Steve said, to display RichText data, you need the RichText control. Quite simple.
If the RichText data contains an image AND other data, like text or tables, things are different and much more complicated. In that case you need the NotesMIME classes to get the HTML representation of the RichText data, parse it, extract references to the image you want, then run through all MIME items to find the one holding the image data.
So in a nutshell: when the RichText contains the image alone, it's easy and Steve gave a good example. Otherwise it's complicated.