Hi everyone.
In last month i was dealing with REST Api services mostly from client perspective and i realized how much people don’t care about documentation of their APIs. That’s Crazy! There was even one company who hadn’t any docs at all! They just sent me their real-time generated docs (seriously?) as we were talking on messenger and almost all of it were WRONG!
But even when there was a cool and fair documentation, it was still a time consuming task developing every single action in those documents.
So there is something called ApiBlueprint.
It is simply:
A powerful high-level API description language for web APIs.
It is so nice. If you are familiar with apiary you hopefully know what an ApiBlueprint is.
Since ApiBlueprint is fairly rich, I came up with the idea of writing a code generator based on ApiBlueprint that takes .apib
files and convert them to Elixir code for usage.
I’ve named it Prex
Simply Prex can take .apib
file and generate Elixir modules like this:
# Created by Prex
defmodule Example.Posts do
@moduledoc """
This section groups App.net post resources.
"""
@base_url "https://alpha-api.app.net"
###
# API Calls
###
# Post
@doc """
Returns a specific Post.
## Parameters
- postid: The id of the Post.
"""
def retrieve_a_post(postid \\ "") do
req_url = Path.join @base_url, "/stream/0/posts/{post_id}"
HTTPoison.request(:get, req_url, body: Poison.encode!(%{"post_id" => postid}), headers: ["Content-Type": "application/json"])
end
def retrieve_a_post!(postid \\ "") do
{:ok, result} = retrieve_a_post(postid)
result
end
@doc """
Delete a Post. The current user must be the same user who created the Post. It
returns the deleted Post on success.
## Parameters
- postid: The id of the Post.
"""
def delete_a_post(postid \\ "") do
req_url = Path.join @base_url, "/stream/0/posts/{post_id}"
HTTPoison.request(:delete, req_url, body: Poison.encode!(%{"post_id" => postid}), headers: ["Content-Type": "application/json"])
end
def delete_a_post!(postid \\ "") do
{:ok, result} = delete_a_post(postid)
result
end
# Posts Collection
@doc """
Create a new Post object. Mentions and hashtags will be parsed out of the post
text, as will bare URLs...
"""
def create_a_post do
req_url = Path.join @base_url, "/stream/0/posts"
HTTPoison.request(:post, req_url)
end
def create_a_post! do
{:ok, result} = create_a_post()
result
end
@doc """
Retrieves all posts.
"""
def retrieve_all_posts do
req_url = Path.join @base_url, "/stream/0/posts"
HTTPoison.request(:get, req_url)
end
def retrieve_all_posts! do
{:ok, result} = retrieve_all_posts()
result
end
# Stars
@doc """
Save a given Post to the current User’s stars. This is just a “save” action,
not a sharing action.
*Note: A repost cannot be starred. Please star the parent Post.*
## Parameters
- postid: The id of the Post.
"""
def star_a_post(postid \\ "") do
req_url = Path.join @base_url, "/stream/0/posts/{post_id}/star"
HTTPoison.request(:post, req_url, body: Poison.encode!(%{"post_id" => postid}), headers: ["Content-Type": "application/json"])
end
def star_a_post!(postid \\ "") do
{:ok, result} = star_a_post(postid)
result
end
@doc """
Remove a Star from a Post.
## Parameters
- postid: The id of the Post.
"""
def unstar_a_post(postid \\ "") do
req_url = Path.join @base_url, "/stream/0/posts/{post_id}/star"
HTTPoison.request(:delete, req_url, body: Poison.encode!(%{"post_id" => postid}), headers: ["Content-Type": "application/json"])
end
def unstar_a_post!(postid \\ "") do
{:ok, result} = unstar_a_post(postid)
result
end
end
I’ve been working on this for only about 48 hours now. It’s super buggy.
It is going to support SOAP with WSDL too.
I just want to know how much do you think this is useful?
Please share your opinion with me. Even if you think this is very useless.
Thank’s for reading this.