api blueprint

Read more about the article Working with Activity API in Open Event API Server

Working with Activity API in Open Event API Server

Recently, I added the Activities API with documentation and dredd tests for the same in Open Event API Server. The Activity Model in the Open Event Server is basically a log of all the things that happen while the server is running, like - event updates, speaker additions, invoice generations and other similar things. This blogpost explains how to implement Activity API in the Open Event API Server’s nextgen branch. In the Open Event Server, we first add the endpoints, then document these so that the consumers ( Open Event Orga App, Open Event Frontend) find it easy to work with all the endpoints. We also test the documentation against backend implementation to ensure that a end-developer who is working with the APIs is not misled to believe what each endpoint actually does in the server. We also test the documentation against backend implementation to ensure that a end-developer who is working with the APIs is not misled to believe what each endpoint actually does in the server. The Activities API endpoints are based on the Activity database model. The Activity table has four columns - id, actor, time, action, the names are self-explanatory. Now for the API schema, we need to make fields corresponding these columns. Since id is auto generated, we do not need to add it as a field for API. Also the activity model’s __init__ method stamps time with the current system time. So this field is also not required in the API fields. We are left with two fields- actor and action. Defining API Schema Next, we define the API Schema class for Activities model. This will involve a Meta class and fields for the class.The Meta class contains the metadata of the class. This includes details about type_, self_view, self_view_kwargs and an inflect parameter to dasherize the input fields from request body. We define the four fields - id, actor, time and action according to marshmallow fields based on the data type and parameters from the activities model. Since id, actor and action are string columns and time is a DateTime column, the fields are written as following: The id field is marked as dump only because it is a read-only type field. The other fields are marked with allow_none as they are all non-required field. ActivityList Class: The activity list class will provide us with the endpoint: “/v1/activities” This endpoint will list all the activities. Since we wanted only GET requests to be working for this, so defined method = [‘GET’, ] for ResourceList. The activities are to be internally created based on different actions like creating an event, updating an event, adding speakers to sessions and likewise. Since the activities are to be shown only to the server admin, is_admin permission is used from the permission manager. ActivityDetail Class: The activity detail gives methods to work with an activity based on the activity id. The endpoint provided is :  ‘/v1/activity/<int:activity_id>’ Since this is also an admin-only accessible GET only endpoint the following was written: Writing Documentation: The documentation is written…

Continue ReadingWorking with Activity API in Open Event API Server
Read more about the article Using API Blueprint with Yaydoc

Using API Blueprint with Yaydoc

As part of extending the capability of Yaydoc to document APIs, this week we integrated API Blueprint with Yaydoc. Now we can parse apib files and add the parsed content to the generated documentation. From the official Homepage of API Blueprint, API Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs. It is a documentation-oriented web API description language. The API Blueprint is essentially a set of semantic assumptions laid on top of the Markdown syntax used to describe a web API. To Integrate API Blueprint with Yaydoc, we used an sphinx extension named sphinxcontrib-apiblueprint. This extension can directly translate text in API Blueprint format into docutils nodes. The advantage with this approach as compared to using tools like aglio is that the generated html fits in nicely with the already existent theme. Though we may in future provide ability to generate html using tools like aglio if the user prefers. Adding an extension to sphinx is very easy. In the conf.py template, we added the extension to the already enabled list of extensions. extensions += [‘sphinxcontrib.apiblueprint’] The above extension provides a directive apiblueprint which can be then used to include apib files. The directive is very similar to the built in include directive. The difference is just that it should be only be used to include files in API Blueprint format. You can see an example below of how to use this directive. .. apiblueprint:: <path to apib file> Although this is enough for projects which use the ResT markup format, This cannot be used with projects using markdown as the primary markup format, since markdown doesn’t support the concept of directives. To solve this, we used the eval_rst block provided by recommonmark in Yaydoc. It allows users to embed valid ReST within markdown and recommonmark will properly parse the embedded text as ReST. Now a user can use this to use directives within markdown. You can see an example below. ```eval_rst .. apiblueprint:: <path to apib file> ``` In order to implement this, we used the AutoStructify class provided by recommonmark. Here’s a snippet from our conf.py template. Note that this does have far reaching effects. Now users would be able to use this to add constructs like toctree in markdown which wasn’t possible before. from recommonmark.transform import AutoStructify def setup(app): app.add_config_value('recommonmark_config', { 'enable_eval_rst': True, }, True) app.add_transform(AutoStructify) Let’s see all of this in action. Here’s a preview of a generated documentation with API Blueprint using Yaydoc. Resources recommonmark - Official Documentation sphinxcontrib-apiblueprint - Github Repository API Blueprint - Official Homepage

Continue ReadingUsing API Blueprint with Yaydoc
Read more about the article Rendering Open Event Server’s API-Blueprint document

Rendering Open Event Server’s API-Blueprint document

After writing the FOSSASIA's Open Event Server project API- Blueprint Document manually, we wanted to know how we could render the document, how to check it in an HTML-client friendly format and how to make it change the look as we go. In order to do that, we found two rendering ways. They are: 1) The apiary editor: This editor helps us to render API blueprints and print them in user readable API documented format. When we create the API blueprint manually, we always follow the pattern write an api blueprint i.e the name and metadata, then followed by resource groups and actions, which was already discussed in the last blog. In order to use the apiary editor, we start off by creating our first project. Initially during the our first use of this editor, we will get a default “polls and vote” example api project. This is a template we can use as guide. The pole/vote api looks something like this in the editor mode:   Apiary has a facility to test an API, document an API, inspect an API or simply edit an API. We first start off by creating a project “open-event-api”. Next, in the editor mode of the apiary, we add the contents of our api-blueprint documents. Here is an example of how USERS API is rendered. If we get our request and response correctly, on clicking List All Users we will get a good 200 response like this in the editor: However, if we tend to go off format with the api-blueprint, we get an invalid error: The final rendering and how the API result can be seen in the document mode with the respective API’s request and response. The document mode request and response look like this: This rendered doc can be viewed publicly with the link got in the document mode. Similarly, we test it out in the editor for the rest of the ap. This is a simple way to render your api blueprint. 2)  The aglio renderer: Since API blueprint is presented in the form of .apib format, the con side of it is it is not easily viewable by viewers. Even though we use apiary, view the rendered docs along with getting a shareable link, we would surely like the docs for our API server to be hosted in our server as well. So, we use Aglio exactly to do that . It is an API Blueprint renderer which supports multiple themes. It converts the apib file into user readable formats such as pdf, html, etc. Here since we want to host it as a webpage, we render it in the form of .html.  It outputs static HTML of the result and can be served by any web host. Since API Blueprint is a Markdown-based document format, this lets us write API descriptions and documentation in a simple and straightforward way. An example of how aglio rendered document in a three column format looks like: The best thing about Aglio is not…

Continue ReadingRendering Open Event Server’s API-Blueprint document