Open-event-server: Ensure that the API follows JSON-API schema

[niranjan94]

Parent issue: #3457

Currently, the API doesn't follow any standard schema. Ensure it follows the json-api schema

Any of the following libraries can be used:
http://jsonapi.org/implementations/#server-libraries-python

[shubham-padia]

@niranjan94 Since we're using flask-restplus which is using swagger docs. I think it is compliant with the OpenApi specification (previously known as swagger specification). flask-restplus is also listed on http://swagger.io/open-source-integrations/ .

[niranjan94]

shubham-padia swagger spec is a spec for describing an API and its documentation. where as JSON-API spec is a specification for all the response objects, relationships, paths and is widely compatible with a lot of clients.

JSON-API spec and swagger spec are actually do different things meant for two different purposes. We'll still be using swagger for our docs.

[enigmaeth]

How do I get started with this?
I read the docs at http://jsonapi.org/format/ and took an overview of Flask-REST-JSONAPI from the list of the libraries above.

[niranjan94]

@enigmaeth Since this is gonna be a major change to the current API, the first step would be to propose how you're planning to implement it, here ... So, that all can know what is happening and can suggest improvements

[niranjan94]

@shubham-padia @SaptakS @enigmaeth @poush @LuD1161 @magdalenesuo

Please research on this and give in your ideas here.

• How best can this be implemented ?
• Do we stick to Flask-restplus or is there an alternative that has better out-of-the-box support for json-api ?

[shubham-padia]

flask-rest-jsonapi seems like the best choice out of the given libraries and has better out of the box support for json-api. Also according to some testaments, it perfectly couples with emberjs.

[niranjan94]

@shubham-padia that looks like a great library ! 😄

These are the primary things that we require:

• Proper relationship definitions
• Sorting
• Filtering
• Pagination

Looks like Flask-REST-JSONAPI has all of them. Let's keep this mind. We'll see what the rest of them come up.

[shubham-padia]

@niranjan94 I'm having second thoughts about the library. I missed out Flask-restless as it wasn't listed in the implementations link, but it also supports jsonapi spec. Flask-restless has a detailed documentation and has been widely used. Can you have a look at it and provide some feedback from it.
https://github.com/jfinkels/flask-restless
https://flask-restless.readthedocs.org/

[niranjan94]

How well does it support relationship definitions as per json api
specifications?

[niranjan94]

I don't seem to be able to find anything about relationships in the docs. Also, is there sorting support out of the box?

[shubham-padia]

I don't seem to be able to find anything about relationships in the docs

Yes. Seems so, lets leave it then.

[niranjan94]

@shubham-padia cool. Then please proceed with Flask-REST-JSONAPI :)