How can I ommit property from defined MSON? I have defined one simple entity (object) using MSON:
# Data Structures
## Article (object)
Represents an article
## Properties
+ id: 1 (number, optional)
+ name: My first article (string)
## Articles [/articles]
### Get all articles [GET]
Get all articles available on this website.
+ Response 200 (application/json)
+ Attributes (array[Article])
### Create an article [POST]
Create new article.
+ Request (application/json)
+ Attributes (Article)
I'm using Article object in several api endpoints. The problem is that I don't want id to be specified when posting new article so I want to omit it in the documentation for POST method. Is it possible to include Article entity in all endpoints and say what fields I want to omit?
There is no actually way how to do it.
You have two options:
declare id with attribute nullable
Declare Article without id and later inherit from Article and attach id.
# Data Structures
## Article (object)
+ name: My first article (string)
## ArticleInstance (Article)
+ id (number)
## Articles [/articles]
### Get all articles [GET]
Get all articles available on this website.
+ Response 200 (application/json)
+ Attributes (array[Article])
### Create an article [POST]
Create new article.
+ Request (application/json)
+ Attributes (Article)
Related
I have a collection response which gives back an array of user objects and want to have different values for the user attributes without to create multiple user objects. Is there a way to do this?
# Group Users
## Users Collection [/api/v1/users]
### View Users [GET]
+ Request (application/vnd.api+json)
+ Headers
Accept: application/vnd.api+json
Authorization: Bearer JWT
+ Response 200 (application/vnd.api+json)
+ Attributes
+ meta (UsersMetaData)
+ data (array[User, User])
+ links (UserLinks)
# Data Structures
## User
+ type: users (string, required, fixed)
+ id: 1 (number, required)
+ attributes (UserAttributes, required)
## UserAttributes
+ email: test#test.com (string)
+ confirmed: false (boolean)
+ first_name: Melanie (string)
I don't want to create multiple user data structures to avoid an overload. But maybe there is a way to create sample arrays or something to do this in an easy way?
Edit: I just found out this way, in case someone has the same or similar question:
+ Response 200 (application/vnd.api+json)
+ Attributes
+ data (array)
+ (User)
+ attributes (UserAttributes)
+ email: `another#mail.com` (string)
+ confirmed: true (boolean)
+ (User)
+ attributes (UserAttributes)
+ first_name: Darth Vader
This way it is possible to rewrite just the attributes for each object without the need to create new ones.
I am using django rest framework documentation module to document my API.
I am facing a problem in the sense that nested serializers do not appear in my documentation, but only the outermost does.
As an example I have the following code:
class MyFirstSerializer(serializers.Serializer):
some_data = serializers.CharField(help_text="a number")
more_data = serializers.CharField(help_text="a letter")
class MySecondSerializer(serializers.Serializer):
email = serializers.EmailField(help_text="the email address")
number = serializers.CharField(help_text="a number")
another_serializer = MyFirstSerializer(help_text='a JSON structure')
The way the program works, is by having a nested JSON structure. However the documentation modules on mentions the fact that another_serializer is a field, and does not show what kind of data is supposed to be passed, somethinng like:
POST your/endpoint/
Parameter Description
email the email address
number a number
another_serializer a JSON structure
I would like a way for the documentation to be done recursively on all my field, in order to have a complete description of my endpoints, something like:
POST your/endpoint/
Parameter Description
email the email address
number a number
another_serializer
some_data a number
more_data a letter
Resources usually have multiple get methods. Get a singular or get many by query params. How is this represented in blueprint? I can do it using two resources, but that in my opinion is not correct as its the same resource.
Related to this question How does one add PUT to the resource given the uri is defined at the resource level.
Ideally this is how i think things should be written but the editor doesn't like it. I have found in docs where the HTTP_ACTION and URI can be put together, but the editor seems to want the URI at the resource level.
# Storefronts
## Read [GET /v1/storefronts{?query_params...}]
+ Parameter
query_params ...
+ Request Matching Storefronts (application/json)
+ Response 200 (application/json)
## Read [GET /v1/storefronts/{id}]
+ Parameter
+ id (string) ... id for record to return
+ Request (application/json)
+ Response 200 (application/json)
## UPDATE [PUT /v1/storefronts/{id}]
+ Parameter
+ id (string) ... id for record to update
+ Request (application/json)
+ Response 200 (application/json)
Technically you have 2 resources: one representing a single Storefront with an identity (typically supporting GET, PUT, DELETE, PATCH) and one representing a collection of Storefronts (typically supporting GET, POST). Here's how you would represent this in API Blueprint:
# Storefront [/v1/storefronts/{id}]
## Retreive a Single Storefront [GET]
## Update a Storefront [PUT]
## Delete a Storefront [DELETE]
# Storefronts Collection [/v1/storefronts]
## List Storefronts [GET]
## Create a New Storefront [POST]
I have an API contract defined in Apiary and I'm using the Resource model syntax to enable reuse of payloads.
The documentation rendered by Apiary only shows the model name though (eg Response 200 returns a [Foo][]) - without any further details on what Foo is, or any link to view the attributes in the Foo model.
Given a model, how do I see what its attributes are in the rendered documentation?
update
The relevant part of the contract is below:
### Manipulating a specific Organisation [/organisations/{id}]
Operations to retrieve and update a specific Organisation.
+ Parameters
+ id (required, guid, `F339ADA5-E836-40FE-8E90-BEF06892762E`) ... The guid Organisation `id`.
+ Model (application/json)
+ Headers
Link : <http://foobar.com/organisations/F339ADA5-E836-40FE-8E90-BEF06892762E>;rel="self"
+ Body
{
"id" : "F339ADA5-E836-40FE-8E90-BEF06892762E",
"name" : "joe's gardening supplies"
}
### Retrieve an Organisation [GET]
+ Response 200
[Organisation][]
### Update an Organisation [PATCH]
+ Request
[Organisation][]
+ Response 204
Unless you provide an example, it's just guessing, but my first guess would be wrong level of indentation. How example blueprint could look like:
FORMAT: 1A
HOST: http://www.google.com
# Model Example
Notes API is a *short texts saving* service similar to its physical paper presence on your table.
# Group Notes
Notes related resources of the **Notes API**
## Note [/notes/{id}]
A single Note object with all its details
+ Parameters
+ id (required, number, `1`) ... Numeric `id` of the Note to perform action with. Has example value.
+ Model
+ Header
X-My-Header: The Value
+ Body
{ "id": 2, "title": "Pick-up posters from post-office" }
### Retrieve a Note [GET]
+ Response 200 (application/json)
[Note][]
### Remove a Note [DELETE]
+ Response 204
Code above results in this documentation, where model is correctly incorporated on places where it's referenced (and where such reference is supported - i.e. definition of payload).
Sometimes it's helpful to read the raw version of Apiary's docs on GitHub, because it's easier to spot the right, exact format that way.
ok, from comparing the two examples I've worked it out.
in my contract the model reference
[Organisation][]
was indented two tabs instead of one. :S
that's a really easy mistake to make - would be helpful if Apiary flagged the incorrect indentation level for a model reference.
How can I read the section a certain URI belongs to?
I want to enhance the mod_breadcrumb to put section and category into the HTML. JApplication->getPathway() returns a JPathway which basically holds an assiciative array combining a name and an URL (as $list[]->name and $list[]->link). I think, it should be possible to get the section and category from a link, but don't know how.
A starting point could be the parsing into JURI-Object, but from there I don't know how get get further. Any ideas?
Pretty straight forward...
I assume you want to add category and section for the article and not your custom component.
Check if requested current URL is for article. If it is for article you know the article ID, use this article Id to go database and get catid from #__content, Use this cat_id to go to #__categories and get section (this is section id), go to #__sections to get the proper section name. All this can be done in 1 sql statement.
$breadcrumbs =& JFactory::getApplication()->getPathway();
$breadcrumbs->addItem("SECTION_NAME", JRoute::_("index.php?option=com_content&view=section&id=SECTION_ID"));
$breadcrumbs->addItem("CATEGOY_NAME", JRoute::_("index.php?option=com_content&view=category&id=CATEGORY_ID"));
$breadcrumbs->addItem("Article");
Alternatively, if you know the URL from the breadcrumb item. You can parse it and get IDS. The trick here is not to get the default URI object by JFactory::getURI() because things will get ugly, use JFactory::getURI('YOU_URI_NAME').
<?php
// You need to get Your own uri, you do not want to modify default URI
// because this will messup a lot of things
$uri = JFactory::getURI('MyCustomURI');
// Test # 1 [ID = SECTION_ID]
$url = "index.php?option=com_content&view=section&id=SECTION_ID";
$uri->parse($url);
echo "CURRENT SECTION = " . (int) $uri->getVar('id');
// Test # 2 [ID = 123]
$url = "index.php?option=com_content&view=section&id=123";
$uri->parse($url);
echo "CURRENT SECTION = " . (int) $uri->getVar('id');
?>