Search code examples
apiweb-servicesapi-design

Single API endpoint pros and cons

I am creating API and trying to figure out is planned approach any good.
That API is not public and it will be used by SPA and mobile app that I build.
So I am thinking of GraphQL-like design but without posting json and with regular HTTP methods. Something like this for GET methods:

Example 1 - get users with specific fields(_join indicates sql table join), ordering and limit:
api.com?table=users&displayFields=id,name,email,address,tel,country_join&orderBy=asc&orderColumn=name&offset=0&limit=10

Example 2 - get users based on search parameters with all fields, ordering and limit:
api.com?table=users&search=John&searchFields=name,email&orderBy=asc&orderColumn=name&offset=0&limit=10

I assume this is bad since REST is standard, otherwise I would see much more examples of this approach.
But why is this bad? For me it seems easier to develop and more flexible to use.
Is proper REST API for examples I provided easier to implement, safer, easier to use or cache?

Solution

  • The main difference I see between putting the variables in the url vs the request body are:

    • the length of the data as the url length is limited while the request body is not
    • special characters to be escaped in the url which can lead to long and unclear url

    These are 2 pros in favor of data in request body, but I agree that data in url is much simpler to test and use as tou don't need an http client tool like curl or postman to validate your endpoints.

    REST however has stricter conventions if you want to fully implement it:

    • use the right http requests (get, post, patch, delete and put) to implement crud operations on one single endpoint
    • return the right http code as a result
    • use standard data format for input and output (json or XML)

    For better interoperability between systems it's advised to comply with REST and microservices design patterns.

    For small applications we can follow some shortcuts and not comply fully. I have integrated several services so far and each time I can tell you no one of them implements standard REST :-)