Open Source Social Network API

OpenAPI 3.0 specification schema and collections of API for building or integrating social networking feature in an application. Project also includes controller generator script using Postman export

Comment 5

Inspiration/Introduction

There were many times when there was a requirement to add social networking elements to an existing applications or requirement to create niche social network came to me, as having a niche social network is becoming popular these days as people are losing trust from giants like Facebook. To fullfill these requirements I tried out multiple alternative both open source and commercial. The open source alternatives like Elgg was good for a full blown social network, but it was weak when it comes to integrating it to existing application as the API support was a bit lacking. Meanwhile the commercial API had a hefty premium price to give the features I needed to implement basic social networking capabilities.

Solution ?

Introducing OSSNAPI (Open Source Social Networking API), a social network api philosophy designed from ground up using API first development approach, designed an built to be flexible to fit most of requirement , easy to implement and robust. The POSTMAN public workspace contains all essential tools you would require to setup your own server or client library. The workspace consist of first class mock serve, visualisers , testing kit , documentation and multiple collection useful for different purposes.

You can read more about my submission idea here - https://physcocode.com/postman-api-hackathon/

Or You can deep dive into the design concept of OSSNAPI here - https://physcocode.com/ossn-api-open-source-social-networking-api-design-concept/

What it does

This project is divided into 2 phase:

  • Create a complete specification schema (using OpenAPI 3.0) and setup all the tools provided by POSTMAN to create the OSSN platform using API first development approach
  • Build a server that implements this schema and can be used as a backend to create social application

The OSSNAPI defines implementation of following API:

  • User API collection - Collection of API's to manage users
  • Posts API collection - Collection of API to manage posts that can range from small tweets to a full image post or even a slide of images
  • Like and Comment API collection - API to manage likes and comments attached to posts
  • User Relation API collection - Collection of api to mange relation between users (friends,follow,cirecles etc)
  • Messaging API collection - Collection of api for building 1-1 or group
  • Feed API collection - Collection od api to manage activity feed

The OSSNAPI defines following model:

  • User - to store and retrieve user data
  • Post - this is the basic backbone of social feature, a post can be anything from short tweets, to image based post
  • Feed - this is used to store interaction between users , user and post and other activity of users. Eg : X likes a post , X is now friends with Y etc. These activities can then be displayed on feed
  • Like - store list of all user who likes a particular post
  • Comments - store all the comments for a post
  • UserRelation - this stores relation between two users , this can be used to implement relations like 'friends', 'follow' or something as complex as 'circles' that was introduced by Google +
  • Message - this stores messeges sent in groups or 1-1 interaction
  • MessageRoom - this stores the messaging rooms , rooms can be 1-1 messaging rooms or group message rooms. Message rooms are where messages are exchanged

The OpenAPI specification schema can be found on the public workspace or you can visit here - https://github.com/OSSNAPI/OpenAPI-spec

The work in progress server side implementation of the specification can be found here - https://github.com/OSSNAPI/OSSN-server-php

How I built it

  • Every good project starts with a session of brain storming and finding a project that would be helpful to people. Once the idea kicks in I prefer creating a whole rough sketch before jumping in!

  • Firstly I created a OpenAPI 3.0 schema that defines 28 APIs divided into 7 different collection. The schema is complete with example and have lots of comments to be understandable. The thing I kept in mind while designing schema was to make it really readable and create it as inspiration for other community members

Schema is available at - https://github.com/OSSNAPI/OpenAPI-spec

Preview of beautifully commented schema

  • Once the schema was ready I used the schema to generate a mock server, most of the heavy lifting was done by POSTMAN and with little tweaks like setting a few env variables and fixing few responses and request I had a fully working mock server and mock collection !

Mock Server is available at - https://4a0282ff-75d3-4d18-a863-01496b8a2d3e.mock.pstmn.io

Preview of mock server

  • Then I duplicated the mock server collection to create a collection for my development environment, but something was missing , the ugly json didn't feel like a social media , so I fixed this problem by using POSTMAN's Visualizer to create visual representation of posts, activity feed and comments. Make API development great again!

Preview of visualizer

  • Once Mock server and dev env was ready I shifted my complete focus to documentation, firstly I created a collection for documentation with folder structure slightly adjusted to make the document much more readable , then using the POSTMAN desktop application I described each and every collection and API in as much detail as I can. Then Viola! POSTMAN's documenter created a beautiful documentation.

Documentation is available at - https://documenter.getpostman.com/view/1722111/TW6tLq53

Preview of document

  • Last bit was setting a few collection that would be used for testing the implementation, specially contract testing. Would be building test suits soon once the server side implementation is at a good stage. The server side implementations test environment is almost ready using ** CircleCI orb** and Postman's powerful test suit

  • Over ? Nah , not yet now that the API is ready it was time to start building the server side implementation. Easy right ? there are so many generators something might help me up running quickly ! But sadly no :( , while there are multiple generators for creating client side SDK but server side generator to create controllers and stub were limited, so I made my own !

Introducing PHP server controller generator using POSTMAN collection exports !

I created a simple Generator that takes in json exported from Postman and turn it into PHP Controllers, these controllers are then filled with stubs (Basically the controller returns values provided by postman examples when they are called). One of the issue with the generator is to keep the work easy I did not add support for nested folder inside collection so I had to create a new collection with no folder just all API in a single place and used it to export json that was then used to generate controllers

Currently Generator is created to work perfectly with Scrawler Framework but with slight alterations it can be used to generate Controllers for any framework. The benefit of using it with Scrawler was that Scrawler automatically creates route end points once controller is created

Code for generator and more more info can be found at - https://github.com/OSSNAPI/Php-Controller-Generator

The collection that was created to automatically generate Controllers can be found at - https://www.getpostman.com/collections/d4d7a8cc60f816a5abb0

If you would like to know more about Scrawler (The framework being used to create server side implementation of specification ) you can go at - https://github.com/scrawler-php/scrawler or https://scrawler.io

Challenges I ran into

Accomplishments that I am proud of / What we learned

I am proud that I learned about API first development approach and actually implemented a project using the same, I would really like to thank POSTMAN for presenting this opportunity, I learned about lot of new things like mock server, OpenAPI 3.0 and much more even though I have been using POSTMAN for quite a while (about 2-3 years)

What all was created as part of Hackathon

What POSTMAN features did I use

  • OpenAPI - API specification was created using OpenAPI 3.0 and was written in the postman's awesome editor
  • Mock Server - Mock server was generated using the schema and then was tweaked to provide a useful mocking ecosystem
  • Visualizer - The new Beta visualizer feature was used to build GUI for posts, activity feed and comments so that developers can actually feel there API and not just look at boring JSON
  • Collection - For building multiple collection for different purposes like generator, document, mock , dev testing etc
  • Documenter - For Generating beautiful documents for the API specification, which can be run in postman and make development a breeze
  • Enviornment variables - To switch in between Mock , dev and prod env
  • Collection Export - The exported json was used to generate server side Controller to help speeding up development of server side implementation

What's next for Open Source Social Media API

  • Add more detailed error codes in OpenAPI 3.0 schema
  • Improving specifications and bringing complex feature like groups
  • Creating a fully managed hosted API service for commercial values backed by POSTMAN's powerful monitor and test system
  • Keeping the server side implementation in active development parallel with API schema
  • Creating more tools to make development easier using API first development approach and POSTMAN

Thank You

You can ask questions or send suggestions by opening issue at - https://github.com/OSSNAPI/OpenAPI-spec

Or you can directly contact me by filling form at - https://physcocode.com/contact/

Built With

+ 8 more
Share this project:

Updates