Quirks of uploading aspx files to a document library using SharePoint REST API

Uploading a file to a SharePoint document library using the SharePoint REST API can be very straight forward. Fast forward to Microsoft Docs and you are presented with all the information you need.
A simple construct:

Create a file and add it to a folder

url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/add(url='a.txt',overwrite=true)
method: POST
body: "Contents of file"
Headers: 
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value
    content-length:length of post body

Update a file by using the PUT method

url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/$value
method: POST
body: "Contents of file."
Headers: 
    Authorization: "Bearer " + accessToken
    X-RequestDigest: form digest value
    X-HTTP-Method:"PUT"
    content-length:length of post body

The next thing to figure out is permissions. Anyone who has worked with SharePoint would know that for basic file operations like Add/Edit one would only require Edit/Contribute rights on the library. And that is it. Basically, that would work for all kinds of file upload.

Enter "aspx" files. Read on for the twist.

Recently a client tried this and we were baffled by a completely unexplained behavior.

Problem Synopsis
Client generates reports on their Linux environment as 'aspx' pages. These .aspx pages are then uploaded to a document library on SharePoint. This aspx page is then viewed by the multitude as a dashboard for certain information. This was initially being done manually. The client wished to automate the upload using the SP REST API.

Everything went smooth with writing a script using CURL to facilitate the upload. However, there was an observed difference in behavior when the file was uploaded using UI/explorer view vs when uploaded via REST.

When uploaded via the UI/Explorer view, users could navigate to the library, click on the file and the file was presented in the browser as a web page.
When uploaded via REST, clicking on the file didn't open the file as a web page. The user was always being prompted to download the file.

We started tracing HTTP traffic, comparing file contents but nothing turned up that could indicate what caused this behavior.

The end user unknowingly started playing around with permissions for the account that was used to upload the files using REST. He had started with "Contribute". He then elevated to "Edit" and then finally "Full Control" (this matched his own permissions when he uploaded the file using UI). And voila!!! The uploaded file could be opened. He had done something unknowingly but it worked.

We were initially of the opinion that this could be one of the many surprises that SharePoint is packed with. There are no documentation for these but over the years, we have come to accept these as part of the SharePoint journey. It still didn't seem to add up and then we moved our entire focus to permissions.

It is now that we realized that SharePoint treats aspx pages (even those uploaded to a document library) as pages. Because of this, if the account that uploads aspx pages lacks the "Add and Customize Pages  -  Add, change, or delete HTML pages or Web Part Pages, and edit the Web site using a Microsoft SharePoint Foundation-compatible editor." then SharePoint treats this as a file an no longer serves it as a web page when requested.

Solution
So, we then started to work towards a final solution:

• Created a new permission level with only the permission to ‘Add and Customize Pages ‘
• Changed the permission level ‘Full Control’ for the account used for upload with this new permission level
• Validated an upload - and it worked!!!

So, the takeaway is that if you are uploading aspx pages to a document library and they are intended to be used as web pages, it is not sufficient to have Add/Edit items permission. You also require "Add and Customize Pages" permission on the library.