REST API和静态页面（最佳解决方案）

Question

I am relatively new in API development. I often face with different problems and have a lot of questions. Major question is "How to implement something following best practices and patterns".
My goal is not just to write API and forget about it, but maintain and make it easy to use for others.

Now I have question about static pages and JSON response.
On my site I have some amount of static pages (About Us, Contact Us, Shipping, Payment......) so pages with static context essentially html and images.

So I need to have this pages in my app (in this case Android Standalone App) as part of the app, but they shouldn't be hardcoded instead they will be downloaded from site using API, to keep them updated.

I have some questions :

1. How URL should look like, should it be some amount of constant url ( http://supersite.com/api/aboutus,http://supersite.com/api/contactus ...). Or it should look like http://supersite.com/api/articles/42 ?

2. How should JSON response structure look like. The problem here is that content of static pages is quite different, for instance Contact Us page will have such important information: phone numbers, emails and can be independent properties in JSON response. About Us page have another main parts. And there can be a lot of such pages. How to keep this unified ?

3. Maybe it is better to unify JSON responses just into serveral properties (short description, full text, image ...) and send raw text or even html and do work on a client. But it seems not to be a good idea.

Maybe there is another correct way to implement this. Or it is not be part API at all and should be done in another way.

I would be grateful for everyone, thanks for help in advance.

Answer 1

I recommend to follow the REST API design. In your case you have just static pages. That means you could have URLs like:

GET    /api/pages/{id}
POST   /api/pages
PUT    /api/pages/{id}

Your {id} can be primary key (int), guid or unique string. In case of static web pages I generally recommend use SeoUrl (about-us, contact-us)

When your data structure is variable, you can create key-value pairs or list of objects. It can looks like this:

{
   "name":"About Us",
   "id":"about-us",
   "text":"Some HTML text",
   "properties":[
      {
         "key":"phone",
         "value":"72273726",
         "order":1
      },
      {
         "key":"email",
         "value":"[e-mail]",
         "order":2
      }
   ]
}

Of course, there is more ways and final solution is definitely up to you. Try to search articles related to "restful api design".